Skip to content

WebAuthn

Login users using WebAuthn biometrics integrated into your native login experience. Although WebAuthn authentication and registration is initiated in the frontend, the flows are completed using a backend-to-backend integration. The client-side integration can also be implemented using the Transmit Platform SDK.

Download OpenAPI description
backend-webauthn.openapi.json
backend-webauthn.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/

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

Register for logged-out user

Request

Complete WebAuthn credential registration for a new user (in Transmit) or a user that isn't currently logged in via Transmit. This API must be called from the backend using a client access token. If successful, the credentials will be registered for the user corresponding to the external user ID in the request. If no user is found, a new user will be created.

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.

external_user_idstringrequired

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

user_emailstring

The user's primary email address

curl -i -X POST \
  https://api.sbx.transmitsecurity.io/cis/v1/auth/webauthn/external/register \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "webauthn_encoded_result": "string",
    "external_user_id": "string",
    "user_email": "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
}