Skip to content

One-Time Login

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

Download OpenAPI description
backend-one-time-login.openapi.json
backend-one-time-login.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/

Send email link

Request

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.

Security
ClientAccessToken
Bodyapplication/jsonrequired
emailstringrequired

Email of the user

Example: "name@example.com"
redirect_uristringrequired

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.

Example: "https://www.example.com/verify"
email_contentobject
statestring

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_expirationnumber

invitation link expiration in minutes

channelstring

Channel to use to send the magic link

Enum"email""direct"
client_attributesobject
generate_request_idboolean

The request ID can serve as an additional security identifier for authentication requests. When set to 'false' (by default), the request ID isn't returned. When set to 'true', Mosaic generates a unique request ID that must be included in the subsequent Authenticate OTP request along with other required parameters.

Default false
curl -i -X POST \
  https://api.sbx.transmitsecurity.io/cis/v1/auth/link/email/send \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "email": "name@example.com",
    "redirect_uri": "https://www.example.com/verify",
    "email_content": {
      "subject": "string",
      "primaryColor": "#6981FF",
      "base64logo": "string",
      "headerText": "string",
      "bodyText": "string",
      "linkText": "string",
      "infoText": "string",
      "footerText": "If you didn'\''t request this email, you can safely ignore it.",
      "senderName": "string"
    },
    "state": "string",
    "email_expiration": 0,
    "channel": "email",
    "client_attributes": {
      "user_agent": "string",
      "ip_address": "string"
    },
    "generate_request_id": false
  }'

Responses

Backend auth initialized successfully.

Bodyapplication/json
messagestringrequired
Example: "Email sent successfully"
Response
application/json
{
  "message": "Email sent successfully"
}

Send OTP

Request

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

Security
ClientAccessToken
Bodyapplication/jsonrequired
channelstringrequired

Channel to use to send the OTP

Enum"sms""email""direct"
identifier_typestringrequired

Type of user identifier used for login

Enum"email""phone_number""user_id""username"
identifierstringrequired

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.

email_contentobject
custom_sms_inputobject
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"}
custom_emailstring

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

custom_phone_numberstring

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

client_attributesobject
expires_innumber

Number of minutes until the OTP expires

generate_request_idboolean

The request ID can serve as an additional security identifier for authentication requests. When set to 'false' (by default), the request ID isn't returned. When set to 'true', Mosaic generates a unique request ID that must be included in the subsequent Authenticate OTP request along with other required parameters.

Default false
curl -i -X POST \
  https://api.sbx.transmitsecurity.io/cis/v1/auth/otp/send \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "channel": "sms",
    "identifier_type": "email",
    "identifier": "string",
    "email_content": {
      "subject": "string",
      "primaryColor": "#6981FF",
      "base64logo": "string",
      "headerText": "string",
      "bodyText": "string",
      "linkText": "string",
      "infoText": "string",
      "footerText": "If you didn'\''t request this email, you can safely ignore it.",
      "senderName": "string"
    },
    "custom_sms_input": {
      "custom_message": "string",
      "sender_id": "string"
    },
    "approval_data": {
      "transaction_id": "eFII2y40uB9hQ98nXt3tc1IHkRt8GrRZiqZuRn_59wT",
      "sum": "200"
    },
    "custom_email": "string",
    "custom_phone_number": "string",
    "client_attributes": {
      "user_agent": "string",
      "ip_address": "string"
    },
    "expires_in": 0,
    "generate_request_id": false
  }'

Responses

Backend auth initialized successfully.

Bodyapplication/json
messagestringread-onlyrequired
Example: "OTP sent"
approval_dataobjectread-only

Approval data object, if passed in the request.

Example: {"transaction_id":"eFII2y40uB9hQ98nXt3tc1IHkRt8GrRZiqZuRn_59wT","sum":"200"}
codestringread-only

One time passcode, if the channel is direct.

Example: "123456"
Response
application/json
{
  "message": "OTP sent",
  "approval_data": {
    "transaction_id": "eFII2y40uB9hQ98nXt3tc1IHkRt8GrRZiqZuRn_59wT",
    "sum": "200"
  },
  "code": "123456"
}

Authenticate OTP

Request

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.

Security
ClientAccessToken
Bodyapplication/jsonrequired
resourcestring

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.

claimsobject

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.

Example: {"id_token":{"roles":null}}
org_idstring

Organization ID, used for member login in B2B scenarios

client_attributesobject
session_idstring

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.

passcodestringrequired

OTP to validate

identifier_typestringrequired

Type of user identifier used for sending the OTP

Enum"email""phone_number""user_id""username"
identifierstringrequired

User identifier that the OTP was sent to

request_idstring

The request ID. This is a mandatory parameter if you’ve previously requested to generate a request ID when sending OTP or email link.

curl -i -X POST \
  https://api.sbx.transmitsecurity.io/cis/v1/auth/otp/authenticate \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "resource": "string",
    "claims": {
      "id_token": {
        "roles": null
      }
    },
    "org_id": "string",
    "client_attributes": {
      "user_agent": "string",
      "ip_address": "string"
    },
    "session_id": "string",
    "passcode": "string",
    "identifier_type": "email",
    "identifier": "string",
    "request_id": "string"
  }'

Responses

Returns user tokens

Bodyapplication/json
access_tokenstringrequired

User access token for accessing endpoints on behalf of the authenticated user.

id_tokenstring

ID token that identifies the user.

refresh_tokenstring

Refresh token used to refresh an expired access token.

token_typestringrequired

Bearer.

expires_innumberrequired

Expiration time of the access token in seconds.

Default 3600
session_idstringrequired

ID of the session in which the authentication occurs.

Response
application/json
{
  "access_token": "string",
  "id_token": "string",
  "refresh_token": "string",
  "token_type": "string",
  "expires_in": 3600,
  "session_id": "string"
}