TOTP

Download OpenAPI specification:Download

Login using time-based one-time passcodes (TOTP), which can be generated by authenticator apps like Google Authenticator. This provides passwordless, two-factor authentication using a single login method.

Authenticate TOTP

Authenticates a user using a TOTP code generated by the user's authenticator app. Once the TOTP is validated using the secret created upon registration and the TOTP method configuration, user tokens are returned.

SecurityOAuth2: ClientAccessToken
Request
Request Body schema: application/json
required
resource
string

Resource URI the authentication request is attempting to access, which is reflected in the audience (aud claim) of the access token. This must be configured as resource for the application.

object

Used to request additional claims in the ID token, such as roles, permissions, and other user profile data. The structure is per the OIDC Standard. For supported claims and how to request custom claims, see the ID Token Reference.

org_id
string

Organization ID, used for member login in B2B scenarios

object

Client attributes

session_id
string

Used to associate the authentication with an existing session (such as for MFA). If unspecified, a new session is created and the session ID is returned.

token
required
string

TOTP code to validate

identifier_type
string
Default: "email"

Type of user identifier used for validating the TOTP

Enum: "email" "phone_number" "user_id" "username"
identifier
required
string

Identifier of the user that the TOTP was generated for

Responses
200

Returns user tokens

post/v1/auth/totp/authenticate
Request samples
application/json
{
  • "resource": "string",
  • "claims": {
    },
  • "org_id": "string",
  • "client_attributes": {
    },
  • "session_id": "string",
  • "token": "string",
  • "identifier_type": "email",
  • "identifier": "string"
}
Response samples
application/json
{
  • "access_token": "string",
  • "id_token": "string",
  • "refresh_token": "string",
  • "token_type": "string",
  • "expires_in": 3600,
  • "session_id": "string"
}

Start a transaction signing flow with TOTP

Start a transaction signing flow with TOTP. Receive a challenge to add to the authenticator app.

SecurityOAuth2: ClientAccessToken
Request
Request Body schema: application/json
required
resource
string

Resource URI the authentication request is attempting to access, which is reflected in the audience (aud claim) of the access token. This must be configured as resource for the application.

object

Used to request additional claims in the ID token, such as roles, permissions, and other user profile data. The structure is per the OIDC Standard. For supported claims and how to request custom claims, see the ID Token Reference.

org_id
string

Organization ID, used for member login in B2B scenarios

object

Client attributes

session_id
string

Used to associate the authentication with an existing session (such as for MFA). If unspecified, a new session is created and the session ID is returned.

approval_data
required
object

Flat object that contains the data that your customer should approve for a transaction signing or custom approval flow. It can contain up to 10 keys, and only alphanumeric characters, underscores, hyphens, and periods. It will be returned as a claim in the ID token upon successful authentication.

identifier_type
required
string

Type of user identifier used for login

Enum: "email" "phone_number" "user_id" "username"
identifier
required
string

User identifier, which may correspond to the user's email, phone number, username, or user ID. The type of identifier should be specified as the identifier_type.

Responses
200

Backend auth initialized successfully.

post/v1/auth/totp/transaction/start
Request samples
application/json
{
  • "resource": "string",
  • "claims": {
    },
  • "org_id": "string",
  • "client_attributes": {
    },
  • "session_id": "string",
  • "approval_data": {
    },
  • "identifier_type": "email",
  • "identifier": "string"
}
Response samples
application/json
{
  • "approval_data": {
    },
  • "challenge": "123456"
}

Authenticate transaction signing TOTP

Authenticates a user using a TOTP code generated by the user's authenticator app with the challenge received from the transaction start. Once the TOTP is validated using the secret created upon registration and the TOTP method configuration, user tokens are returned.

SecurityOAuth2: ClientAccessToken
Request
Request Body schema: application/json
required
resource
string

Resource URI the authentication request is attempting to access, which is reflected in the audience (aud claim) of the access token. This must be configured as resource for the application.

object

Used to request additional claims in the ID token, such as roles, permissions, and other user profile data. The structure is per the OIDC Standard. For supported claims and how to request custom claims, see the ID Token Reference.

org_id
string

Organization ID, used for member login in B2B scenarios

object

Client attributes

session_id
string

Used to associate the authentication with an existing session (such as for MFA). If unspecified, a new session is created and the session ID is returned.

token
required
string

TOTP code to validate

identifier_type
string
Default: "email"

Type of user identifier used for validating the TOTP

Enum: "email" "phone_number" "user_id" "username"
identifier
required
string

Identifier of the user that the TOTP was generated for

Responses
200

Returns user tokens

post/v1/auth/totp/transaction/authenticate
Request samples
application/json
{
  • "resource": "string",
  • "claims": {
    },
  • "org_id": "string",
  • "client_attributes": {
    },
  • "session_id": "string",
  • "token": "string",
  • "identifier_type": "email",
  • "identifier": "string"
}
Response samples
application/json
{
  • "access_token": "string",
  • "id_token": "string",
  • "refresh_token": "string",
  • "token_type": "string",
  • "expires_in": 3600,
  • "session_id": "string"
}

Register TOTP

Registers a TOTP authenticator for the logged-in user. The response contains the secret and other configuration that will be used to generate TOTP codes for authentication. The app must provide it to the user (such as via QR) so the user can complete the process using their authenticator app.

Note:

  • A TOTP authenticator is considered registered even if it wasn't added to an authenticator app.
  • A user can only have a single TOTP authenticator for a given application. Attempting to register another will fail, unless your request enables override or you first revoke the authenticator that's currently registered.

SecurityHTTP: UserAccessToken
Request
Request Body schema: application/json
required
label
string

Account name displayed in the authenticator app. If unspecified, the user's email, username, or phone number will be used (ordered by preference).

allow_override
boolean
Default: false

If true, overrides the TOTP secret if one already exists

Responses
201

The TOTP authenticator has been successfully registered.

post/v1/users/me/totp
Request samples
application/json
{
  • "label": "John Doe",
  • "allow_override": false
}
Response samples
application/json
{
  • "secret": "string",
  • "uri": "string"
}

Revoke my TOTP

Unregisters the TOTP authenticator of the currently logged-in user.

SecurityHTTP: UserAccessToken
Responses
204

Revoked

post/v1/users/me/totp/revoke
Request samples 
Revoke TOTP
Unregisters a user's TOTP authenticator


SecurityOAuth2: ClientAccessToken 
Request 
path Parameters
userId
required
string
ID of the user


 
Responses 
204
Revoked


post/v1/users/{userId}/totp/revoke
Request samples