One-Time Login

Download OpenAPI specification:Download

Login users using one-time login methods like magic links or OTPs. This implements a backend-to-backend integration for authentication.

Send email link

Send a magic link by email to a user. Upon clicking the email link, the User Agent will be redirected to the requested redirect URI with a code (passed in the code query parameter). This code can be used to complete the authentication in the subsequent request.

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

Email of the user

redirect_uri
required
string

URI that receives a code when the user clicks the email link. This is your server GET endpoint used to complete the authentication, and should accept 'code' as a query parameter. This URI must be configured as an allowed redirect URI for your Transmit client.

object

Texts, logo and color to render email template with

state
string

An opaque string that is used to maintain state between the request and the callback. It will be added to the redirect URI as a query parameter, which should be validated by your server to protect against cross-site request forgery (CSRF) attacks

email_expiration
number

invitation link expiration in minutes

channel
string

Channel to use to send the magic link

Enum: "email" "direct"
object

Client attributes

Responses
200

Backend auth initialized successfully.

post/v1/auth/link/email/send
Request samples
application/json
{
  • "email": "name@example.com",
  • "redirect_uri": "https://www.example.com/verify",
  • "email_content": {
    },
  • "state": "string",
  • "email_expiration": 0,
  • "channel": "email",
  • "client_attributes": {
    }
}
Response samples
application/json
{
  • "message": "Email sent successfully"
}

Send OTP

Send a one-time passcode to a user by email or SMS.

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

Channel to use to send the OTP

Enum: "sms" "email" "direct"
identifier_type
required
string

Type of user identifier used for login

Enum: "email" "phone_number" "user_id" "username"
identifier
required
string

User identifier, which may correspond to the user's email, phone number, username, or user ID. The type of identifier should be specified as the identifier_type.

object

Texts, logo and color to render email template with, if the channel is email

object

Custom SMS message to send, if the channel is sms

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.

custom_email
string

Custom email to send the OTP to, can be different than the user's email (if the channel is email)

custom_phone_number
string

Custom phone number to send the OTP to, can be different than the user's phone number (if the channel is sms)

object

Client attributes

Responses
200

Backend auth initialized successfully.

post/v1/auth/otp/send
Request samples
application/json
{
  • "channel": "sms",
  • "identifier_type": "email",
  • "identifier": "string",
  • "email_content": {
    },
  • "custom_sms_input": {
    },
  • "approval_data": {
    },
  • "custom_email": "string",
  • "custom_phone_number": "string",
  • "client_attributes": {
    }
}
Response samples
application/json
{
  • "message": "OTP sent",
  • "approval_data": {
    },
  • "code": "123456"
}

Authenticate OTP

Authenticates a user using a one-time passcode that was sent to them by email or SMS. This API validates the code provided by the user and returns user tokens.

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

object

Client attributes

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.

passcode
required
string

OTP to validate

identifier_type
required
string

Type of user identifier used for sending the OTP

Enum: "email" "phone_number" "user_id" "username"
identifier
required
string

User identifier that the OTP was sent to

Responses
200

Returns user tokens

post/v1/auth/otp/authenticate
Request samples
application/json
{
  • "resource": "string",
  • "claims": {
    },
  • "org_id": "string",
  • "client_attributes": {
    },
  • "session_id": "string",
  • "passcode": "string",
  • "identifier_type": "email",
  • "identifier": "string"
}
Response samples
application/json
{
  • "access_token": "string",
  • "id_token": "string",
  • "refresh_token": "string",
  • "token_type": "string",
  • "expires_in": 3600,
  • "session_id": "string"
}