Auth Sessions

Download OpenAPI specification:Download

Manage sessions that provide context for WebAuthn APIs

Start authorized session

Start authorized auth session for user flows that include registration, such as onboarding new users or offering WebAuthn registration to users that logged in using a legacy system or other Transmit login methods. This session must be authorized using an access token that's either fetched using client credentials, or was returned by another Transmit authentication. It must be called from the client backend

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

Username used to specify the user context. If using an access token from a user authentication (via other Transmit APIs), it must match the user associated with the token.

session_expiration
number

Session timeout in seconds

redirect_uri
string

URI required to complete the WebAuthn flow. This URI must also be configured as an allowed redirect URI in the Transmit Admin Portal

device_public_key
string

A public key in a PEM format that will cryptographically bind the device to the credentials. Providing it will enforce double signing for the registered credential

Responses
200

Auth session created

400
401
404
post/v1/auth-session/start-with-authorization
Request samples
application/json
{
  • "username": "string",
  • "session_expiration": 0,
  • "redirect_uri": "string",
  • "device_public_key": "string"
}
Response samples
application/json
{
  • "auth_session_id": "string"
}

Authorize session

Authorize an auth session to an authorized state. for user flows that include registration, such as onboarding new users or offering WebAuthn registration to users that logged in using a legacy system or other Transmit login methods. This session must be authorized using an access token that's either fetched using client credentials, or was returned by another Transmit authentication. It must be called from the client backend.

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

Session identifier

client_id
string
Deprecated

Your client ID. Must match the client ID in the token

username
required
string

Username used to specify the user context. If using an access token from a user authentication (via other Transmit APIs), it must match the user associated with the token.

Responses
200

Auth session authorized

400
401
404
post/v1/auth-session/authorize
Request samples
application/json
{
  • "auth_session_id": "string",
  • "client_id": "string",
  • "username": "string"
}
Response samples
application/json
{
  • "error_code": "invalid_request",
  • "message": "Invalid request: property should not be null or undefined"
}

Start unauthorized session

Start unauthorized auth session for user flows that only include authentication or recovery (not registration, which required an authorized session). This call must be made from the client.

Request
header Parameters
User-Agent
string

Browser user agent. Allows adding device info to sessions if provided

Request Body schema: application/json
required
session_expiration
number

Session timeout in seconds

client_id
required
string

Your client ID

object

Data used in cross-device flows

redirect_uri
string

URI required to complete the WebAuthn flow. This URI must also be configured as an allowed redirect URI in the Transmit Admin Portal

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

Auth session created

400
404
post/v1/auth-session/start-restricted
Request samples
application/json
{
  • "session_expiration": 0,
  • "client_id": "string",
  • "cross_device": {
    },
  • "redirect_uri": "string",
  • "approval_data": {
    }
}
Response samples
application/json
{
  • "auth_session_id": "string"
}

Get session status

Get the status of an auth session in cross-device flows (e.g., if the authenticating device was attached) and obtain the authorization code to exchange for user tokens

Request
header Parameters
x-ts-device-binding-token
string

Device binding token, returned by the first client-side request from a device in the session (in the set-device-binding-token response header)

Request Body schema: application/json
required
auth_session_id
required
string

Session identifier

Responses
200

Auth session status

400
401
404
post/v1/auth-session/status
Request samples
application/json
{
  • "auth_session_id": "string"
}
Response samples
application/json
{
  • "session_status": "in-progress",
  • "cross_device_status": "pending-attachment",
  • "cross_device_result": {
    }
}

Attach to auth session

Attach another device to an existing session for cross-device flows (e.g., when a QR code is scanned)

Request
header Parameters
User-Agent
string

Browser user agent. Allows adding device info to sessions if provided

Request Body schema: application/json
required
auth_session_id
required
string

Session identifier

user_agent
string

Browser user agent. Allows adding device info to sessions if provided

Responses
200

Device binding info

400
404
post/v1/auth-session/attach-device
Request samples
application/json
{
  • "auth_session_id": "string",
  • "user_agent": "string"
}
Response samples
application/json
{
  • "binding_info": {
    }
}

Detach from auth session

Detach a device from an existing authentication session for cross-device flows. Invalidates device binding token for this device, and updates the cross-device status to completed

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

Session identifier

Responses
200

Device detached

400
404
post/v1/auth-session/detach-device
Request samples
application/json
{
  • "auth_session_id": "string"
}
Response samples
application/json
{
  • "error_code": "invalid_request",
  • "message": "Invalid request: property should not be null or undefined"
}