Skip to content

Auth Sessions

Manage sessions that provide context for WebAuthn APIs

Download OpenAPI description
auth-sessions.openapi.json
auth-sessions.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 authorized sessionDeprecated

Request

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

Security
ClientAccessToken
Bodyapplication/jsonrequired
usernamestringrequired

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_expirationnumber

Session timeout in seconds

redirect_uristring

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_keystring

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

curl -i -X POST \
  https://api.sbx.transmitsecurity.io/cis/v1/auth-session/start-with-authorization \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "username": "string",
    "session_expiration": 0,
    "redirect_uri": "string",
    "device_public_key": "string"
  }'

Responses

Auth session created

Bodyapplication/json
auth_session_idstringrequired

Session ID to provide back to the browser. Must be embedded in client-side API calls.

Response
application/json
{
  "auth_session_id": "string"
}

Authorize sessionDeprecated

Request

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.

Security
ClientAccessToken
Bodyapplication/jsonrequired
auth_session_idstringrequired

Session identifier

usernamestringrequired

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.

client_idstringDeprecated

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

curl -i -X POST \
  https://api.sbx.transmitsecurity.io/cis/v1/auth-session/authorize \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "auth_session_id": "string",
    "client_id": "string",
    "username": "string"
  }'

Responses

Auth session authorized

Response
No content

Start unauthorized sessionDeprecated

Request

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.

Headers
User-Agentstring

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

Bodyapplication/jsonrequired
session_expirationnumber

Session timeout in seconds

client_idstringrequired

Your client ID

cross_deviceobject
redirect_uristring

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

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-session/start-restricted \
  -H 'Content-Type: application/json' \
  -H 'User-Agent: string' \
  -d '{
    "session_expiration": 0,
    "client_id": "string",
    "cross_device": {
      "binding_message": "string"
    },
    "redirect_uri": "string",
    "approval_data": {
      "transaction_id": "eFII2y40uB9hQ98nXt3tc1IHkRt8GrRZiqZuRn_59wT",
      "sum": "200"
    }
  }'

Responses

Auth session created

Headers
set-device-binding-tokenstring

A token that binds the device to the session

Example: "8ac0bdca-affb-4b1b-af50-2f834ad266b3"
Bodyapplication/json
auth_session_idstringrequired

Session ID to provide back to the browser. Must be embedded in client-side API calls.

Response
application/json
{
  "auth_session_id": "string"
}

Get session statusDeprecated

Request

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

Headers
x-ts-device-binding-tokenstring

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

Bodyapplication/jsonrequired
auth_session_idstringrequired

Session identifier

curl -i -X POST \
  https://api.sbx.transmitsecurity.io/cis/v1/auth-session/status \
  -H 'Content-Type: application/json' \
  -H 'x-ts-device-binding-token: string' \
  -d '{
    "auth_session_id": "string"
  }'

Responses

Auth session status

Bodyapplication/json
session_statusstringrequired

Indicates global session status. A session is completed only once the authorization code is exchanged for tokens

Enum"in-progress""completed"
cross_device_statusstringrequired

Indicates device status in a cross-device flow. The status is completed only once the device is detached

Enum"pending-attachment""attached""registered""authenticated""completed"
cross_device_resultobject
Response
application/json
{
  "session_status": "in-progress",
  "cross_device_status": "pending-attachment",
  "cross_device_result": {
    "auth_code": "string"
  }
}

Attach to auth sessionDeprecated

Request

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

Headers
User-Agentstring

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

Bodyapplication/jsonrequired
auth_session_idstringrequired

Session identifier

user_agentstring

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

curl -i -X POST \
  https://api.sbx.transmitsecurity.io/cis/v1/auth-session/attach-device \
  -H 'Content-Type: application/json' \
  -H 'User-Agent: string' \
  -d '{
    "auth_session_id": "string",
    "user_agent": "string"
  }'

Responses

Device binding info

Headers
set-device-binding-tokenstring

A token that binds the device to the session

Example: "8ac0bdca-affb-4b1b-af50-2f834ad266b3"
Bodyapplication/json
binding_infoobjectrequired
binding_info.​binding_messagestring

Message provided in the session start request, which should be displayed to the user to prevent phishing attacks

binding_info.​originating_deviceobjectrequired
binding_info.​originating_device.​device_infoobjectrequired
binding_info.​originating_device.​device_info.​osTypestringrequired
binding_info.​originating_device.​device_info.​osVersionstringrequired
binding_info.​originating_device.​device_info.​browserTypestringrequired
binding_info.​originating_device.​device_info.​browserVersionstringrequired
binding_info.​approval_dataobject

Approval data provided when the session was started for an approval signing flow

Response
application/json
{
  "binding_info": {
    "binding_message": "string",
    "originating_device": { … },
    "approval_data": {}
  }
}

Detach from auth sessionDeprecated

Request

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

Bodyapplication/jsonrequired
auth_session_idstringrequired

Session identifier

curl -i -X POST \
  https://api.sbx.transmitsecurity.io/cis/v1/auth-session/detach-device \
  -H 'Content-Type: application/json' \
  -d '{
    "auth_session_id": "string"
  }'

Responses

Device detached

Response
No content