Start authentication

Start registration

Request

Starts a WebAuthn registration process on a secondary device, and returns a challenge for the client to sign. If successful, the response will contain a credential_creation_options field that should be passed in the WebAuthn navigator.credentials.create() API call.

Note: Some fields (user.id and challenge) in the credential_creation_options object are base64 encoded and must first be decoded and converted to an array buffer. It is recommended to use the webauthn-json library that handles this.

Bodyapplication/jsonrequired

cross_device_ticket_idstringrequired

cross device ticket id returned from the init cross device registration API

curl -i -X POST \
  https://api.sbx.transmitsecurity.io/cis/v1/auth/webauthn/cross-device/register/start \
  -H 'Content-Type: application/json' \
  -d '{
    "cross_device_ticket_id": "string"
  }'

Responses

Bodyapplication/json

webauthn_session_idstringrequired

WebAuthn session identifier

credential_creation_optionsobjectrequired

credential_creation_options.attestationstring

Default "none"

Value"none"

credential_creation_options.authenticatorSelectionobject

credential_creation_options.extensionsobject

credential_creation_options.excludeCredentialsArray of strings

credential_creation_options.pubKeyCredParamsArray of objectsrequired

credential_creation_options.pubKeyCredParams[].algnumberrequired

credential_creation_options.pubKeyCredParams[].typestringrequired

Key type. Should always be public-key

Default "public-key"

Value"public-key"

Example: "public-key"

credential_creation_options.timeoutnumber

credential_creation_options.challengestringrequired

credential_creation_options.userobjectrequired

credential_creation_options.user.idstringrequired

User handle

credential_creation_options.user.namestringrequired

The webauthn username

credential_creation_options.user.displayNamestringrequired

The user display name

credential_creation_options.rpobjectrequired

credential_creation_options.rp.idstring/^[a-zA-Z0-9][a-zA-Z0-9-]{1,61}[a-zA-Z0-9]\.[...required

Relying Party ID. Must be a valid domain pre-configured in the Admin Portal for the application

credential_creation_options.rp.namestringrequired

Relying party displayable name

credential_creation_options.rp.iconstringrequired

Response

application/json

{
  "webauthn_session_id": "string",
  "credential_creation_options": {
    "attestation": "none",
    "authenticatorSelection": { … },
    "extensions": { … },
    "excludeCredentials": [ … ],
    "pubKeyCredParams": [ … ],
    "timeout": 0,
    "challenge": "string",
    "user": { … },
    "rp": { … }
  }
}

Init logged-in registration

Request

Initializes a flow that will register WebAuthn credentials using a secondary device. Requested by the access device (e.g., desktop) and requires a logged-in user. Returns cross_device_ticket_id, which should be passed to the biometric device to start the device registration, such as by encoding it in a QR code.

Security

UserAccessToken

Bodyapplication/jsonrequired

usernamestringrequired

Account name for this Relying Party. This is used both for display purposes, as well as during recovery flows where the user is asked for the account name.

limit_single_credential_to_deviceboolean

Set to True in order to limit the creation of multiple credentials for the same account on a single authenticator. Default is False.

Default false

curl -i -X POST \
  https://api.sbx.transmitsecurity.io/cis/v1/auth/webauthn/cross-device/register/init \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "username": "string",
    "limit_single_credential_to_device": false
  }'

Responses

Bodyapplication/json

cross_device_ticket_idstringrequired

Identifies the cross-device flow. Required for starting the flow on the secondary device.

Response

application/json

{
  "cross_device_ticket_id": "string"
}

Init logged-out registration

Request

Initializes a flow that will register WebAuthn credentials using a secondary device. Requested by the access device (e.g., desktop) for a user that isn't logged in via Transmit (e.g., after password login via an external identity provider). Returns cross_device_ticket_id, which should be passed to the biometric device to start the device registration, such as by encoding it in a QR code.

Required permissions: apps:execute, [appId]:execute, auth:execute.

Security

ClientAccessToken

Bodyapplication/jsonrequired

external_user_idstring[ 1 .. 64 ] charactersrequired

A unique identifier in the tenant, which corresponds to an identifier of the user in your system.

usernamestringrequired

Account name for this Relying Party. This is used both for display purposes, as well as during recovery flows where the user is asked for the account name.

curl -i -X POST \
  https://api.sbx.transmitsecurity.io/cis/v1/auth/webauthn/cross-device/external/register/init \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "external_user_id": "string",
    "username": "string"
  }'

Responses

Bodyapplication/json

cross_device_ticket_idstringrequired

Identifies the cross-device flow. Required for starting the flow on the secondary device.

Response

application/json

{
  "cross_device_ticket_id": "string"
}

Complete registration

Request

Completes WebAuthn credential registration for the user on a secondary device. For a logged-in registration flow, the user is derived from the access token. For a logged-out registration flow, the user corresponds to the requested external user ID. If no user is found, a new user will be created.

Required permissions: apps:execute, [appId]:execute, auth:execute.

Security

ClientAccessToken

Bodyapplication/jsonrequired

webauthn_encoded_resultstringrequired

WebAuthn attestation data returned by the browser upon credential creation, which must be converted from array buffer to a base64 string. If webauthn-json create() was used, this is already taken care of.

curl -i -X POST \
  https://api.sbx.transmitsecurity.io/cis/v1/auth/webauthn/cross-device/register \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "webauthn_encoded_result": "string"
  }'

Responses

Registered credential details

Bodyapplication/json

webauthn_session_idstringrequired

WebAuthn session identifier

user_idstring

Transmit user ID, autogenerated upon user creation

webauthn_usernamestringrequired

Name of user account, as specified in the WebAuthn registration

credential_idstringrequired

WebAuthn credential ID

authenticator_attachmentstringrequired

The authenticators' attachment modalities. Cross-platform authenticator are external to the current device, such as a USB security key or a different device

Enum"platform""cross-platform"

aaguidstring

The authenticator's AAGUID

external_user_idstringrequired

External User identifier

is_user_createdbooleanrequired

Indicates if this is a new user or not

Response

application/json

{
  "webauthn_session_id": "string",
  "user_id": "string",
  "webauthn_username": "string",
  "credential_id": "string",
  "authenticator_attachment": "platform",
  "aaguid": "string",
  "external_user_id": "string",
  "is_user_created": true
}

Abort cross-device flow

Request

Terminates the cross-device flow from the auth device, and updates the status to aborted.

Required permissions: apps:execute, [appId]:execute, auth:execute.

Security

ClientAccessToken

Bodyapplication/jsonrequired

cross_device_ticket_idstringrequired

Webauthn cross device ticket ID

curl -i -X POST \
  https://api.sbx.transmitsecurity.io/cis/v1/auth/webauthn/cross-device/abort \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "cross_device_ticket_id": "string"
  }'

Responses

Response

No content

Get cross-device status

Request

Checks the status of a cross-device flow. This is used by the access device.

Query

cross_device_ticket_idstringrequired

curl -i -X GET \
  'https://api.sbx.transmitsecurity.io/cis/v1/auth/webauthn/cross-device/status?cross_device_ticket_id=string'

Responses

Bodyapplication/json

statusstringrequired

Enum"pending""scanned""success""error""timeout""aborted"

session_idstringrequired

session id return on cross device authentication success

Response

application/json

{
  "status": "pending",
  "session_id": "string"
}

Attach device

Request

Indicates that the auth device has engaged in the flow, such as when the user scans a QR encoding the cross-device ticket ID. This updates the flow status to scanned.

Bodyapplication/jsonrequired

cross_device_ticket_idstringrequired

Webauthn cross device ticket ID

curl -i -X POST \
  https://api.sbx.transmitsecurity.io/cis/v1/auth/webauthn/cross-device/attach-device \
  -H 'Content-Type: application/json' \
  -d '{
    "cross_device_ticket_id": "string"
  }'

Responses

Bodyapplication/json

statusstringrequired

Enum"pending""scanned""success""error""timeout""aborted"

started_atstring

approval_dataobject

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"}

Response

application/json

{
  "status": "pending",
  "started_at": "string",
  "approval_data": {
    "transaction_id": "eFII2y40uB9hQ98nXt3tc1IHkRt8GrRZiqZuRn_59wT",
    "sum": "200"
  }
}

Init authentication

Request

Initializes a flow that will authenticate WebAuthn credentials using a secondary device. Requested by the access device (e.g., desktop) before delegating authentication to another device. Returns a cross-device ticket ID that should be passed to the biometric device to start the authentication (e.g., by encoding it in a QR code).

Bodyapplication/jsonrequired

client_idstringrequired

The client ID of the application the user is trying to authenticate to.

usernamestring

Name of user account, as used in the WebAuthn registration. If not provided, the authentication will start without the context of a user and it will be inferred by the chosen passkey

approval_dataobject

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"}

curl -i -X POST \
  https://api.sbx.transmitsecurity.io/cis/v1/auth/webauthn/cross-device/authenticate/init \
  -H 'Content-Type: application/json' \
  -d '{
    "client_id": "string",
    "username": "string",
    "approval_data": {
      "transaction_id": "eFII2y40uB9hQ98nXt3tc1IHkRt8GrRZiqZuRn_59wT",
      "sum": "200"
    }
  }'

Responses

Bodyapplication/json

cross_device_ticket_idstringrequired

Identifies the cross-device flow. Required for starting the flow on the secondary device.

Response

application/json

{
  "cross_device_ticket_id": "string"
}

Start authentication

Request

Start a WebAuthn authentication process using a secondary device. If successful, the response will contain a credential_request_options field that should be passed in the WebAuthn navigator.credentials.get() API call.

Note: Some fields (challenge and each id in the allowCredentials list) in the credential_request_options object are base64 encoded and must first be decoded and converted to array buffer. It is recommended to use the webauthn-json library that handles this.

Bodyapplication/jsonrequired

cross_device_ticket_idstringrequired

Returned upon initializing the authentication flow

curl -i -X POST \
  https://api.sbx.transmitsecurity.io/cis/v1/auth/webauthn/cross-device/authenticate/start \
  -H 'Content-Type: application/json' \
  -d '{
    "cross_device_ticket_id": "string"
  }'

Responses

Bodyapplication/json

webauthn_session_idstringrequired

WebAuthn session identifier

credential_request_optionsobjectrequired

credential_request_options.allowCredentialsArray of objectsrequired

credential_request_options.allowCredentials[].typestringrequired

Key type. Should always be public-key

Default "public-key"

Value"public-key"

Example: "public-key"

credential_request_options.allowCredentials[].idstringrequired

The credential ID

credential_request_options.allowCredentials[].transportsArray of stringsrequired

Default ["internal"]

Items Value"internal"

Example: ["internal"]

credential_request_options.rawChallengestring

Represents the natural WebAuthn challenge. Will Only be present in approval flows

credential_request_options.challengestringrequired

credential_request_options.timeoutnumber

credential_request_options.rpIdstring/^[a-zA-Z0-9][a-zA-Z0-9-]{1,61}[a-zA-Z0-9]\.[...required

Relying Party ID. Must be a valid domain pre-configured in the Admin Portal for the application

credential_request_options.attestationstring

Default "none"

Value"none"

Example: "none"

credential_request_options.userVerificationstring

Default "preferred"

Enum"preferred""required"

Example: "preferred"

credential_request_options.extensionsobject

Response

application/json

{
  "webauthn_session_id": "string",
  "credential_request_options": {
    "allowCredentials": [ … ],
    "rawChallenge": "string",
    "challenge": "string",
    "timeout": 0,
    "rpId": "string",
    "attestation": "none",
    "userVerification": "preferred",
    "extensions": {}
  }
}

WebAuthn Cross-Device

Start registration

Request

Responses

Init logged-in registration

Request

Responses

Init logged-out registration

Request

Responses

Complete registration

Request

Responses

Abort cross-device flow

Request

Responses

Get cross-device status

Request

Responses

Attach device

Request

Responses

Init authentication

Request

Responses

Start authentication

Request

Responses