Skip to content

TOTP

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.

Download OpenAPI description
backend-totp.openapi.json
backend-totp.openapi.yaml
Languages
Servers
Sandbox environment
https://api.sbx.transmitsecurity.io/cis/
Production environment (US)
https://api.transmitsecurity.io/cis/
Production environment (EU)
https://api.eu.transmitsecurity.io/cis/
Production environment (CA)
https://api.ca.transmitsecurity.io/cis/
Production environment (AU)
https://api.au.transmitsecurity.io/cis/

Authenticate TOTP

Request

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.

Security
ClientAccessToken
Bodyapplication/jsonrequired
resourcestring

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.

claimsobject
Example: {"id_token":{"roles":null}}
org_idstring

Organization ID, used for member login in B2B scenarios

client_attributesobject
session_idstring

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.

tokenstringrequired

TOTP code to validate

identifier_typestring

Type of user identifier used for validating the TOTP

Default "email"
Enum"email""phone_number""user_id""username"
identifierstringrequired

Identifier of the user that the TOTP was generated for

curl -i -X POST \
  https://api.sbx.transmitsecurity.io/cis/v1/auth/totp/authenticate \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "resource": "string",
    "claims": {
      "id_token": {
        "roles": null
      }
    },
    "org_id": "string",
    "client_attributes": {
      "user_agent": "string",
      "ip_address": "string"
    },
    "session_id": "string",
    "token": "string",
    "identifier_type": "email",
    "identifier": "string"
  }'

Responses

Returns user tokens

Bodyapplication/json
access_tokenstringrequired

User access token for accessing endpoints on behalf of the authenticated user.

id_tokenstring

ID token that identifies the user.

refresh_tokenstring

Refresh token used to refresh an expired access token.

token_typestringrequired

Bearer.

expires_innumberrequired

Expiration time of the access token in seconds.

Default 3600
session_idstringrequired

ID of the session in which the authentication occurs.

Response
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

Request

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

Security
ClientAccessToken
Bodyapplication/jsonrequired
resourcestring

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.

claimsobject
Example: {"id_token":{"roles":null}}
org_idstring

Organization ID, used for member login in B2B scenarios

client_attributesobject
session_idstring

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_dataobjectrequired

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.

Example: {"transaction_id":"eFII2y40uB9hQ98nXt3tc1IHkRt8GrRZiqZuRn_59wT","sum":"200"}
identifier_typestringrequired

Type of user identifier used for login

Enum"email""phone_number""user_id""username"
identifierstringrequired

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.

curl -i -X POST \
  https://api.sbx.transmitsecurity.io/cis/v1/auth/totp/transaction/start \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "resource": "string",
    "claims": {
      "id_token": {
        "roles": null
      }
    },
    "org_id": "string",
    "client_attributes": {
      "user_agent": "string",
      "ip_address": "string"
    },
    "session_id": "string",
    "approval_data": {
      "transaction_id": "eFII2y40uB9hQ98nXt3tc1IHkRt8GrRZiqZuRn_59wT",
      "sum": "200"
    },
    "identifier_type": "email",
    "identifier": "string"
  }'

Responses

Backend auth initialized successfully.

Bodyapplication/json
approval_dataobjectread-onlyrequired

Approval data object.

Example: {"transaction_id":"eFII2y40uB9hQ98nXt3tc1IHkRt8GrRZiqZuRn_59wT","sum":"200"}
challengestringread-onlyrequired

Totp transaction challenge

Example: "123456"
Response
application/json
{
  "approval_data": {
    "transaction_id": "eFII2y40uB9hQ98nXt3tc1IHkRt8GrRZiqZuRn_59wT",
    "sum": "200"
  },
  "challenge": "123456"
}

Authenticate transaction signing TOTP

Request

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.

Security
ClientAccessToken
Bodyapplication/jsonrequired
resourcestring

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.

claimsobject
Example: {"id_token":{"roles":null}}
org_idstring

Organization ID, used for member login in B2B scenarios

client_attributesobject
session_idstring

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.

tokenstringrequired

TOTP code to validate

identifier_typestring

Type of user identifier used for validating the TOTP

Default "email"
Enum"email""phone_number""user_id""username"
identifierstringrequired

Identifier of the user that the TOTP was generated for

curl -i -X POST \
  https://api.sbx.transmitsecurity.io/cis/v1/auth/totp/transaction/authenticate \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "resource": "string",
    "claims": {
      "id_token": {
        "roles": null
      }
    },
    "org_id": "string",
    "client_attributes": {
      "user_agent": "string",
      "ip_address": "string"
    },
    "session_id": "string",
    "token": "string",
    "identifier_type": "email",
    "identifier": "string"
  }'

Responses

Returns user tokens

Bodyapplication/json
access_tokenstringrequired

User access token for accessing endpoints on behalf of the authenticated user.

id_tokenstring

ID token that identifies the user.

refresh_tokenstring

Refresh token used to refresh an expired access token.

token_typestringrequired

Bearer.

expires_innumberrequired

Expiration time of the access token in seconds.

Default 3600
session_idstringrequired

ID of the session in which the authentication occurs.

Response
application/json
{
  "access_token": "string",
  "id_token": "string",
  "refresh_token": "string",
  "token_type": "string",
  "expires_in": 3600,
  "session_id": "string"
}

Register TOTP

Request

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.

Security
UserAccessToken
Bodyapplication/jsonrequired
labelstring

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

Example: "John Doe"
allow_overrideboolean

If true, overrides the TOTP secret if one already exists

Default false
curl -i -X POST \
  https://api.sbx.transmitsecurity.io/cis/v1/users/me/totp \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "label": "John Doe",
    "allow_override": false
  }'

Responses

The TOTP authenticator has been successfully registered

Bodyapplication/json
secretstringread-onlyrequired

The secret key used to generate the TOTP code. It can be provided to the user to enter manually into the authenticator app.

uristringrequired

A URI containing the secret and other configuration used to generate the TOTP code. It can be encoded in a QR code for the user to scan using their authenticator app

Response
application/json
{
  "secret": "string",
  "uri": "string"
}

Revoke my TOTP

Request

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

Security
UserAccessToken
Bodyapplication/jsonrequired
authenticator_idstring

Authenticator ID to revoke

curl -i -X POST \
  https://api.sbx.transmitsecurity.io/cis/v1/users/me/totp/revoke \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "authenticator_id": "string"
  }'

Responses

Revoked

Revoke TOTP

Request

Unregisters a user's TOTP authenticator.

Required permissions: apps:delete, [appId]:delete, authenticators:delete.

Security
ClientAccessToken
Path
userIdstringrequired

ID of the user

Bodyapplication/jsonrequired
authenticator_idstring

Authenticator ID to revoke

curl -i -X POST \
  'https://api.sbx.transmitsecurity.io/cis/v1/users/{userId}/totp/revoke' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "authenticator_id": "string"
  }'

Responses

Revoked