One-Time Login

Download OpenAPI specification:Download

Login users using one-time login methods like magic links or OTPs. This implements a frontend integration for authentication, where the client obtains an authorization code that your app can exchange in the backend for user tokens.

Send email link

Send a magic link by email to a user

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

Email of the user

redirect_uri
required
string

URI that will receive the authorization code. This is the server GET endpoint used to call the token endpoint, and should accept 'code' as a query parameter. This URI must also be configured as an allowed redirect URI in the Transmit Admin Portal.

create_new_user
boolean
Default: false

Indicates whether to create a new user at the end of the authentication flow if a user is not found for the provided email. If enabled, public signups must also be configured as allowed for the application.

resource
string

URI of the resource the 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.

object

Texts, logo and color to render email template with

require_mfa
boolean
Default: false

Require multi factor authentication for this authentication request.

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.

object

Login attributes

org_id
string

Organization ID, used for member login in B2B scenarios

Responses
200
400
404
post/v1/auth/links/email
Request samples
application/json
{
  • "email": "name@example.com",
  • "redirect_uri": "https://www.example.com/verify",
  • "create_new_user": false,
  • "resource": "string",
  • "email_content": {
    },
  • "require_mfa": true,
  • "claims": {
    },
  • "client_attributes": {
    },
  • "org_id": "string"
}
Response samples
application/json
{
  • "message": "Email sent successfully"
}

Send email OTP

Send a one-time passcode (OTP) by email to the given email address.

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

Email of the user

redirect_uri
required
string

URI that will receive the authorization code. This is the server GET endpoint used to call the token endpoint, and should accept 'code' as a query parameter. This URI must also be configured as an allowed redirect URI in the Transmit Admin Portal.

create_new_user
boolean
Default: false

Indicates whether to create a new user at the end of the authentication flow if a user is not found for the provided email. If enabled, public signups must also be configured as allowed for the application.

resource
string

URI of the resource the 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.

object

Texts, logo and color to render email template with

require_mfa
boolean
Default: false

Require multi factor authentication for this authentication request.

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.

object

Login attributes

org_id
string

Organization ID, used for member login in B2B scenarios

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

User Not Found

post/v1/auth/otp/email
Request samples
application/json
{
  • "email": "name@example.com",
  • "redirect_uri": "https://www.example.com/verify",
  • "create_new_user": false,
  • "resource": "string",
  • "email_content": {
    },
  • "require_mfa": true,
  • "claims": {
    },
  • "client_attributes": {
    },
  • "org_id": "string",
  • "approval_data": {
    }
}
Response samples
application/json
{
  • "message": "OTP email sent",
  • "approval_data": {
    }
}

Validate email OTP

Validate a one-time passcode sent by email to a user. The endpoint will return a URI which can be used to redirect the client in order to complete authentication.

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

Email that the OTP was sent to

passcode
required
string

Email code to validate

response_type
string
Default: "code"

Response type requested for the authentication flow.

Enum: "code" "id_token"
nonce
string

A random value that will associate the client request with the ID token, and used to mitigate replay attacks. It will be added to the ID token and the backend service should only accept ID tokens that include the same nonce value as the one included in the original request.

Responses
200
400
post/v1/auth/otp/email/validation
Request samples
application/json
{
  • "email": "string",
  • "passcode": "string",
  • "response_type": "code",
  • "nonce": "string"
}
Response samples
application/json
{
  • "result": "string"
}

Send SMS OTP

Send a one-time passcode (OTP) by SMS to the given phone number

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

Message to send, must contain {otp} and {app} placeholders to be replaced with one time password and application name. Limited to 140 characters

sender_id
string

The sender name that appears as the message sender on recipients devices. Limited to 11 characters. Limited support see https://docs.aws.amazon.com/sns/latest/dg/sns-supported-regions-countries.html

phone_number
required
string

Phone number to send the OTP to

create_new_user
required
boolean
Default: false

Indicates whether to create a new user at the end of the authentication flow if a user is not found for the provided phone number. If enabled, public signups must also be configured as allowed for the application.

redirect_uri
required
string

URI that will receive the authorization code once the SMS OTP is validated. This is the server GET endpoint used to call the token endpoint, and should accept 'code' as a query parameter. This URI must also be configured as an allowed redirect URI in the Transmit Admin Portal

require_mfa
boolean
Default: false

Require multi factor authentication for this authentication request.

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.

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.

org_id
string

Organization ID, used for member login in B2B scenarios

Responses
200
400
404

User Not Found

post/v1/auth/otp/sms
Request samples
application/json
{
  • "custom_message": "string",
  • "sender_id": "string",
  • "phone_number": "string",
  • "create_new_user": false,
  • "redirect_uri": "string",
  • "require_mfa": true,
  • "claims": {
    },
  • "approval_data": {
    },
  • "org_id": "string"
}
Response samples
application/json
{
  • "message": "SMS sent",
  • "approval_data": {
    }
}

Validate SMS OTP

Validate a one-time passcode sent by SMS to a user. The endpoint will return a URI which can be used to redirect the client in order to complete authentication.

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

Phone number that the SMS OTP was sent to

passcode
required
string

OTP to validate

response_type
string
Default: "code"

Response type requested for the authentication flow.

Enum: "code" "id_token"
nonce
string

A random value that will associate the client request with the ID token, and used to mitigate replay attacks. It will be added to the ID token and the backend service should only accept ID tokens that include the same nonce value as the one included in the original request.

Responses
200
400
post/v1/auth/otp/sms/validation
Request samples
application/json
{
  • "phone_number": "string",
  • "passcode": "string",
  • "response_type": "code",
  • "nonce": "string"
}
Response samples
application/json
{
  • "result": "string"
}

Exchange code for tokenDeprecated

Retrieve ID and access tokens. This API is used to retrieve ID and access tokens using the code that was returned in the redirect URI as a query parameter (for example, when the user clicks a magic link). It may also create a new user if create_new_user was set to true in the send request and no user exists for the email address or phone number (depending on the flow).

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

Authorization code returned in the redirect URI as a query parameter upon successful authentication

client_id
required
string <= 50 characters

Client ID of the application requesting the token

client_secret
required
string <= 50 characters

Client Secret of the application requesting the token

Responses
200
400
post/v1/token
Request samples
application/json
{
  • "code": "GZxLFKTDCnlANVTxNvaWz7AIGPpXqZYSXdAwjiWRuOH",
  • "client_id": "DgsdfhSDsdfhtSDFXCCXBVMKPws345yscv2345XCZV",
  • "client_secret": "FzxvdDMbvxnc45sdfb789XCVGEW6usazxcvbw3KPsb23"
}
Response samples
application/json
{
  • "id_token": "string",
  • "access_token": "string",
  • "refresh_token": "string",
  • "is_user_created": true
}

Logout

Logout the user from a specific session. The user and session are derived from the access token used to authorize the request (which was issued based on the authentication that created the session)

SecurityHTTP: UserAccessToken
Responses
200

Sessions deleted Successfully

400
401
post/v1/auth/logout
Request samples 
Response samples 
application/json
{
  • "sessions_count": 0
}