Skip to content

One-Time Login

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.

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

Required permissions: apps:execute, [appId]:execute, auth:execute.

Security
ClientAccessToken
Bodyapplication/jsonrequired
emailstringrequired

Email of the user

Example: "name@example.com"
redirect_uristringrequired

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.

Example: "https://www.example.com/verify"
create_new_userboolean

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.

Default false
Example: false
resourcestring

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.

email_contentobject
require_mfaboolean

Require multi factor authentication for this authentication request.

Default false
Example: true
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}}
client_attributesobject
org_idstring

Organization ID, used for member login in B2B scenarios

curl -i -X POST \
  https://api.sbx.transmitsecurity.io/cis/v1/auth/links/email \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "email": "name@example.com",
    "redirect_uri": "https://www.example.com/verify",
    "create_new_user": false,
    "resource": "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"
    },
    "require_mfa": true,
    "claims": {
      "id_token": {
        "roles": null
      }
    },
    "client_attributes": {
      "user_agent": "string",
      "ip_address": "string"
    },
    "org_id": "string"
  }'

Responses

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

Send email OTP

Request

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

Required permissions: apps:execute, [appId]:execute, auth:execute.

Security
ClientAccessToken
Bodyapplication/jsonrequired
emailstringrequired

Email of the user

Example: "name@example.com"
redirect_uristringrequired

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.

Example: "https://www.example.com/verify"
create_new_userboolean

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.

Default false
Example: false
resourcestring

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.

email_contentobject
require_mfaboolean

Require multi factor authentication for this authentication request.

Default false
Example: true
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}}
client_attributesobject
org_idstring

Organization ID, used for member login in B2B scenarios

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/otp/email \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "email": "name@example.com",
    "redirect_uri": "https://www.example.com/verify",
    "create_new_user": false,
    "resource": "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"
    },
    "require_mfa": true,
    "claims": {
      "id_token": {
        "roles": null
      }
    },
    "client_attributes": {
      "user_agent": "string",
      "ip_address": "string"
    },
    "org_id": "string",
    "approval_data": {
      "transaction_id": "eFII2y40uB9hQ98nXt3tc1IHkRt8GrRZiqZuRn_59wT",
      "sum": "200"
    }
  }'

Responses

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

Approval data object, if passed in the request.

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

Validate email OTP

Request

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.

Required permissions: apps:execute, [appId]:execute, auth:execute.

Security
ClientAccessToken
Bodyapplication/jsonrequired
emailstringrequired

Email that the OTP was sent to

passcodestringrequired

Email code to validate

response_typestring

Response type requested for the authentication flow.

Default "code"
Enum"code""id_token"
noncestring

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.

curl -i -X POST \
  https://api.sbx.transmitsecurity.io/cis/v1/auth/otp/email/validation \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "email": "string",
    "passcode": "string",
    "response_type": "code",
    "nonce": "string"
  }'

Responses

Bodyapplication/json
resultstringread-onlyrequired

URI used to complete the flow. Sending a GET request to this URI will redirect the browser to your redirect URI with a code to exchange for user tokens.

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

Send SMS OTP

Request

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

Required permissions: apps:execute, [appId]:execute, auth:execute.

Security
ClientAccessToken
Bodyapplication/jsonrequired
custom_messagestring

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

sender_idstring

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_numberstringrequired

Phone number to send the OTP to

create_new_userbooleanrequired

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.

Default false
redirect_uristringrequired

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_mfaboolean

Require multi factor authentication for this authentication request.

Default false
Example: true
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}}
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"}
org_idstring

Organization ID, used for member login in B2B scenarios

curl -i -X POST \
  https://api.sbx.transmitsecurity.io/cis/v1/auth/otp/sms \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "custom_message": "string",
    "sender_id": "string",
    "phone_number": "string",
    "create_new_user": false,
    "redirect_uri": "string",
    "require_mfa": true,
    "claims": {
      "id_token": {
        "roles": null
      }
    },
    "approval_data": {
      "transaction_id": "eFII2y40uB9hQ98nXt3tc1IHkRt8GrRZiqZuRn_59wT",
      "sum": "200"
    },
    "org_id": "string"
  }'

Responses

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

Approval data object, if passed in the request.

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

Validate SMS OTP

Request

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.

Required permissions: apps:execute, [appId]:execute, auth:execute.

Security
ClientAccessToken
Bodyapplication/jsonrequired
phone_numberstringrequired

Phone number that the SMS OTP was sent to

passcodestringrequired

OTP to validate

response_typestring

Response type requested for the authentication flow.

Default "code"
Enum"code""id_token"
noncestring

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.

curl -i -X POST \
  https://api.sbx.transmitsecurity.io/cis/v1/auth/otp/sms/validation \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "phone_number": "string",
    "passcode": "string",
    "response_type": "code",
    "nonce": "string"
  }'

Responses

Bodyapplication/json
resultstringread-onlyrequired

URI used to complete the flow. Sending a GET request to this URI will redirect the browser to your redirect URI with a code to exchange for user tokens.

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

Logout

Request

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)

Security
UserAccessToken
curl -i -X POST \
  https://api.sbx.transmitsecurity.io/cis/v1/auth/logout \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

Sessions deleted Successfully

Bodyapplication/json
sessions_countnumberrequired

Number of logged out sessions

Response
application/json
{
  "sessions_count": 0
}

Exchange code for tokenDeprecated

Request

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).

Bodyapplication/jsonrequired
codestringrequired

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

Example: "GZxLFKTDCnlANVTxNvaWz7AIGPpXqZYSXdAwjiWRuOH"
client_idstring<= 50 charactersrequired

Client ID of the application requesting the token

Example: "DgsdfhSDsdfhtSDFXCCXBVMKPws345yscv2345XCZV"
client_secretstring<= 50 charactersrequired

Client Secret of the application requesting the token

Example: "FzxvdDMbvxnc45sdfb789XCVGEW6usazxcvbw3KPsb23"
curl -i -X POST \
  https://api.sbx.transmitsecurity.io/cis/v1/token \
  -H 'Content-Type: application/json' \
  -d '{
    "code": "GZxLFKTDCnlANVTxNvaWz7AIGPpXqZYSXdAwjiWRuOH",
    "client_id": "DgsdfhSDsdfhtSDFXCCXBVMKPws345yscv2345XCZV",
    "client_secret": "FzxvdDMbvxnc45sdfb789XCVGEW6usazxcvbw3KPsb23"
  }'

Responses

Bodyapplication/json
id_tokenstringrequired
access_tokenstringrequired
refresh_tokenstringrequired
is_user_createdbooleanrequired

Indicates if this is a new user or not

Response
application/json
{
  "id_token": "string",
  "access_token": "string",
  "refresh_token": "string",
  "is_user_created": true
}