WebAuthn

Download OpenAPI specification:Download

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.

Start authentication

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.

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 [ 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

Responses
200

Authentication options

400
401
404
post/v1/auth/webauthn/authenticate/start
Request samples
application/json
{
  • "client_id": "string",
  • "username": "string"
}
Response samples
application/json
{
  • "webauthn_session_id": "string",
  • "credential_request_options": {
    }
}

Authenticate WebAuthn

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

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

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.

claims
object

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.

org_id
string

Organization ID, used for member login in B2B scenarios

session_id
string

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_result
required
string

WebAuthn assertion data (base64 encoded)

Responses
200

Returns user tokens

post/v1/auth/webauthn/authenticate
Request samples
application/json
{
  • "resource": "string",
  • "claims": {
    },
  • "org_id": "string",
  • "session_id": "string",
  • "webauthn_encoded_result": "string"
}
Response samples
application/json
{
  • "access_token": "string",
  • "id_token": "string",
  • "refresh_token": "string",
  • "token_type": "string",
  • "expires_in": 3600,
  • "session_id": "string"
}

Init hosted registration

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

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

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_name
string [ 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_id
string [ 1 .. 64 ] characters

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

redirect_uri
required
string

URI to redirect to upon completing the registration process

Responses
200

Registered credential details

400
404
post/v1/auth/webauthn/external/register/hosted/hint
Request samples
application/json
{
  • "webauthn_identifier": "string",
  • "webauthn_display_name": "string",
  • "external_user_id": "string",
  • "redirect_uri": "string"
}
Response samples
application/json
{
  • "register_webauthn_cred_token": "string"
}

Start registration

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.

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

Your client ID.

username
required
string [ 1 .. 64 ] characters

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_name
string [ 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

Responses
200

Active WebAuthn session info

400
404
post/v1/auth/webauthn/register/start
Request samples
application/json
{
  • "client_id": "string",
  • "username": "string",
  • "display_name": "string"
}
Response samples
application/json
{
  • "webauthn_session_id": "string",
  • "credential_creation_options": {
    }
}

Register for logged-in user

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.

SecurityHTTP: UserAccessToken
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
404
post/v1/auth/webauthn/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"
}

Register for logged-out user

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.

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.

external_user_id
required
string

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

Responses
200

Registered credential details

400
404
post/v1/auth/webauthn/external/register
Request samples
application/json
{
  • "webauthn_encoded_result": "string",
  • "external_user_id": "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
}