Client Actions

Download OpenAPI specification:Download

This backend API is used to report client actions, add the user context and report action results, allowing detection and response reporting and user profiling.

Trigger action event

Report a client action event that occurs in an SDK session

SecurityHTTP: risk_access_token
Request
Request Body schema: application/json
required
session_token
required
string

A token returned by the SDK for the session established upon SDK initialization.

action_type
required
string

The action type

user_id
string

Opaque identifier of the authenticated user in your system.

claimed_user_id
string

User ID of the not yet authenticated user, used to enhance risk and trust assessments. Once the user is authenticated, setAuthenticatedUser should be called.

correlation_id
string

Any ID that could help relate the action with external context or session

object

Transaction data-points given in the relevant action

Responses
201

Trigger action has been received and stored successfully.

400

Bad request

401

Invalid authentication

403

Invalid authorization

429

Rate limit reached

500

Internal error

post/action/trigger-action
Request samples
application/json
{
  • "session_token": "string",
  • "action_type": "transaction",
  • "user_id": "string",
  • "claimed_user_id": "string",
  • "correlation_id": "string",
  • "transaction_data": {
    }
}
Response samples
application/json
{
  • "action_token": "string"
}

Report action result

Reports the result of an action that a recommendation was issued for. This includes whether the user successfully completed the action, and what type of challenge was given to the user (if any).

SecurityHTTP: risk_access_token
Request
Request Body schema: application/json
required
action_token
required
string

The token return when the action event was reported

result
required
string

The action result.

Enum: "success" "failure" "incomplete"
user_id
string

Opaque identifier of the user in your system.

challenge_type
string

Type of challenge used, in case a challenge was recommended for this action event

Enum: "sms_otp" "email_otp" "totp" "push_otp" "voice_otp" "idv" "captcha" "password" "passkey"
Responses
201

Action result has been received and stored successfully.

400

Bad request

401

Invalid authentication

403

Invalid authorization

429

Rate limit reached

500

Internal error

post/action/result
Request samples
application/json
{
  • "action_token": "string",
  • "result": "success",
  • "user_id": "string",
  • "challenge_type": "sms_otp"
}

Set authenticated user

Sets the user context for a client action reported to the SDK. It should be set only after you’ve fully authenticated the user (including, for example, any 2FA that was required).

SecurityHTTP: risk_access_token
Request
query Parameters
get_recommendation
boolean
Default: false

A flag for getting the recommendation for the triggered action (for saving another recommendation backend call)

Request Body schema: application/json
required
user_id
required
string

Opaque identifier of the user in your system.

action_token
required
string

The token return by the SDK when the action was reported.

Responses
201

User Auth has been received and stored successfully.

400

Bad request

401

Invalid authentication

403

Invalid authorization

429

Rate limit reached

500

Internal error

post/action/authenticated-user
Request samples
application/json
{
  • "user_id": "string",
  • "action_token": "string"
}