WebAuthn Cross-Device

Download OpenAPI specification:Download

APIs to manage cross-device flow for WebAuthn registration and authentication.

Start registration

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.

Request
Request Body schema: application/json
required
cross_device_ticket_id
required
string

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

Responses
200
400
404
post/v1/auth/webauthn/cross-device/register/start
Request samples
application/json
{
  • "cross_device_ticket_id": "string"
}
Response samples
application/json
{
  • "webauthn_session_id": "string",
  • "credential_creation_options": {
    }
}

Init logged-in registration

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.

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

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.

Responses
200
400
404
post/v1/auth/webauthn/cross-device/register/init
Request samples
application/json
{
  • "username": "string"
}
Response samples
application/json
{
  • "cross_device_ticket_id": "string"
}

Init logged-out registration

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.

SecurityOAuth2: ClientAccessToken
Request
Request Body schema: application/json
required
external_user_id
required
string [ 1 .. 64 ] characters

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

username
required
string

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.

Responses
200
400
404
post/v1/auth/webauthn/cross-device/external/register/init
Request samples
application/json
{
  • "external_user_id": "string",
  • "username": "string"
}
Response samples
application/json
{
  • "cross_device_ticket_id": "string"
}

Complete registration

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.

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

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.

Responses
200

Registered credential details

400
post/v1/auth/webauthn/cross-device/register
Request samples
application/json
{
  • "webauthn_encoded_result": "string"
}
Response samples
application/json
{
  • "webauthn_session_id": "string",
  • "user_id": "string",
  • "webauthn_username": "string",
  • "credential_id": "string",
  • "authenticator_attachment": "platform",
  • "external_user_id": "string",
  • "is_user_created": true
}

Abort cross-device flow

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

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

Webauthn cross device ticket ID

Responses
204
400
404
post/v1/auth/webauthn/cross-device/abort
Request samples
application/json
{
  • "cross_device_ticket_id": "string"
}
Response samples
application/json
{
  • "error_code": "invalid_request",
  • "message": "Invalid request: property should not be null or undefined"
}

Get cross-device status

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

Request
query Parameters
cross_device_ticket_id
required
string
Responses
200
400
404
get/v1/auth/webauthn/cross-device/status
Request samples 
Response samples 
application/json
{
  • "status": "pending",
  • "session_id": "string"
}
Attach device
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.


Request 
Request Body schema: application/json
required
cross_device_ticket_id
required
string
Webauthn cross device ticket ID


 
Responses 
200
400
404
post/v1/auth/webauthn/cross-device/attach-device
Request samples 
application/json
{
  • "cross_device_ticket_id": "string"
}
Response samples 
application/json
{
  • "status": "pending",
  • "started_at": "string",
  • "approval_data": {
    }
}
Init authentication
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).


Request 
Request Body schema: application/json
required
client_id
required
string
The client ID of the application the user is trying to authenticate to.


 
username
string
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_data
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.


 
Responses 
200
400
404
post/v1/auth/webauthn/cross-device/authenticate/init
Request samples 
application/json
{
  • "client_id": "string",
  • "username": "string",
  • "approval_data": {
    }
}
Response samples 
application/json
{
  • "cross_device_ticket_id": "string"
}
Start authentication
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.


Request 
Request Body schema: application/json
required
cross_device_ticket_id
required
string
Returned upon initializing the authentication flow


 
Responses 
200
400
404
post/v1/auth/webauthn/cross-device/authenticate/start
Request samples 
application/json
{
  • "cross_device_ticket_id": "string"
}
Response samples 
application/json
{
  • "webauthn_session_id": "string",
  • "credential_request_options": {
    }
}