Register for logged-out user

Start authentication

Request

Start a new webauthn authentication. If successful, the response will contain a credential_request_options field that should be passed in the WebAuthn navigator.credentials.get() API call. Note that 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

client_idstringrequired

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

timeoutnumber

The timeout in seconds for the authentication modal. Must be between 30 and 600. Default is 300 seconds.

usernamestring[ 1 .. 64 ] characters

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/authenticate/start \
  -H 'Content-Type: application/json' \
  -d '{
    "client_id": "string",
    "timeout": 0,
    "username": "string",
    "approval_data": {
      "transaction_id": "eFII2y40uB9hQ98nXt3tc1IHkRt8GrRZiqZuRn_59wT",
      "sum": "200"
    }
  }'

Responses

Authentication options

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

Authenticate WebAuthn

Request

Authenticate a user using their WebAuthn credentials. Retrieves tokens based on a the encoded result of the webauthn authentication.

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

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.

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.

webauthn_encoded_resultstringrequired

WebAuthn assertion data (base64 encoded)

curl -i -X POST \
  https://api.sbx.transmitsecurity.io/cis/v1/auth/webauthn/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",
    "webauthn_encoded_result": "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"
}

Init hosted registration

Request

Initializes a hosted WebAuthn registration flow for a logged-out user (see Quickstart). This API is used to securely set the WebAuthn username in the backend, and returns a registration token used to start the registration flow. Relevant only for hosted login scenarios

Security

ClientAccessToken

Bodyapplication/jsonrequired

webauthn_identifierstring[ 1 .. 64 ] charactersrequired

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.

webauthn_display_namestring[ 1 .. 64 ] characters

Human-palatable name for the user account, only for display (max 64 characters). If not set, the username parameter will also act as the display name

external_user_idstring[ 1 .. 64 ] characters

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

redirect_uristringrequired

URI to redirect to upon completing the registration process

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

Responses

Registered credential details

Bodyapplication/json

register_webauthn_cred_tokenstringrequired

Token returned to relying party to ensure the specified username is being used for webauthn credential registration

Response

application/json

{
  "register_webauthn_cred_token": "string"
}

Start registration

Request

Starts a registration of WebAuthn credentials for a specified user, returning a challenge to be signed by the client. If successful, the response will contain a credential_creation_options field that should be passed in the WebAuthn navigator.credentials.create() API call. Note that 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

client_idstringrequired

Your client ID.

usernamestring[ 1 .. 64 ] charactersrequired

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.

display_namestring[ 1 .. 64 ] characters

Human-palatable name for the user account, only for display (max 64 characters). If not set, the username parameter will also act as the display name

timeoutnumber

The timeout in seconds for the registration modal. Must be between 30 and 600. Default is 300 seconds.

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/register/start \
  -H 'Content-Type: application/json' \
  -d '{
    "client_id": "string",
    "username": "string",
    "display_name": "string",
    "timeout": 0,
    "limit_single_credential_to_device": false
  }'

Responses

Active WebAuthn session info

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": { … }
  }
}

Register for logged-in user

Request

Complete WebAuthn credential registration for a user that is currently logged in using a different Transmit authentication method. This API must be called from the backend using the user access token returned upon successful authentication. If successful, the credential will be registered for the user that corresponds to the authorization token.

Security

UserAccessToken

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/register \
  -H 'Authorization: Bearer <YOUR_JWT_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

Response

application/json

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