Skip to content

Passwords

Login users using passwords. This implements a frontend integration for password authentication, where passwords are handled only by the client. If the password credentials are valid, the client can obtain an authorization code that your app can exchange in the backend for user tokens.

Download OpenAPI description
passwords.openapi.json
passwords.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/

Login with password

Request

Authenticate a user with a password

Bodyapplication/jsonrequired
usernamestring

The user's username. Pass either username or email, but not both.

emailstring

The user's primary email address. Pass either username or email, but not both.

phone_numberstring

The user's primary phone number. Pass only one of username, email, or phone_number, but not both.

passwordstringrequired

The user's password

client_idstringrequired

Client ID of the application requesting authentication, retrieved from the Transmit Admin Portal

Example: "c35ab2a.xVShlOVGsUMh3Cqk73K1O.transmit"
redirect_uristringrequired

URI to redirect to upon completion of the IDP flow. 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://domain.com/verify"
resourcestring

Resource URI the login is attempting to access.

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}}
org_idstring

Organization ID, used for member login in B2B scenarios

curl -i -X POST \
  https://api.sbx.transmitsecurity.io/cis/v1/auth/password/login \
  -H 'Content-Type: application/json' \
  -d '{
    "username": "string",
    "email": "string",
    "phone_number": "string",
    "password": "string",
    "client_id": "c35ab2a.xVShlOVGsUMh3Cqk73K1O.transmit",
    "redirect_uri": "https://domain.com/verify",
    "resource": "string",
    "require_mfa": true,
    "claims": {
      "id_token": {
        "roles": null
      }
    },
    "org_id": "string"
  }'

Responses

Bodyapplication/json
resultobjectrequired
result.​urlstringread-only

URL to start the authentication flow. This is only returned if password reset is not required.

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

Start reset by email link

Request

Starts a password reset flow by sending an email magic link. Once clicked, the User Agent will be redirected to the URI specified in this request. This URI will include a code required to reset the password.

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

Security
ClientAccessToken
Bodyapplication/jsonrequired
prev_reset_tokenstring

Reset token that contains mfa_required as true. Should be passed when initiating a second factor authentication, in case MFA is required for password reset flows.

ignore_mfaboolean

Allows resetting the password without MFA in case MFA is required for password reset flows

emailstring

The user's primary email address. Pass either username or email, but not both.

usernamestring

The username to send the magic link to. Pass either username or email, but not both.

redirect_uristringrequired

URI where the email link will redirect to. This is the server GET endpoint used to call the password reset 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/reset-password"
email_contentobject
curl -i -X POST \
  https://api.sbx.transmitsecurity.io/cis/v1/auth/password/reset/email/link \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "prev_reset_token": "string",
    "ignore_mfa": true,
    "email": "string",
    "username": "string",
    "redirect_uri": "https://www.example.com/reset-password",
    "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"
    }
  }'

Responses

Bodyapplication/json
messagestringread-onlyrequired
Example: "Reset password email sent"
Response
application/json
{
  "message": "Reset password email sent"
}

Start reset by Email OTP

Request

Starts a password reset flow by sending an Email OTP.

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

Security
ClientAccessToken
Bodyapplication/jsonrequired
prev_reset_tokenstring

Reset token that contains mfa_required as true. Should be passed when initiating a second factor authentication, in case MFA is required for password reset flows.

ignore_mfaboolean

Allows resetting the password without MFA in case MFA is required for password reset flows

emailstringrequired

The user's primary email address

email_contentobject
curl -i -X POST \
  https://api.sbx.transmitsecurity.io/cis/v1/auth/password/reset/email/otp \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "prev_reset_token": "string",
    "ignore_mfa": true,
    "email": "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"
    }
  }'

Responses

Bodyapplication/json
messagestringread-onlyrequired
Example: "Email Sent"
Response
application/json
{
  "message": "Email Sent"
}

Validate reset OTP Email

Request

Validate a reset password OTP.

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

Security
ClientAccessToken
Bodyapplication/jsonrequired
emailstringrequired

Email address that the OTP was sent to

passcodestringrequired

OTP to validate

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

Responses

Bodyapplication/json
resultstringrequired

Reset token to be used when sending a reset request (/auth/password/reset)

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

Start reset by SMS OTP

Request

Starts a password reset flow by sending an SMS OTP.

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

Security
ClientAccessToken
Bodyapplication/jsonrequired
prev_reset_tokenstring

Reset token that contains mfa_required as true. Should be passed when initiating a second factor authentication, in case MFA is required for password reset flows.

ignore_mfaboolean

Allows resetting the password without MFA in case MFA is required for password reset flows

phone_numberstringrequired

Phone number to send the SMS to, specified in E.164 format

Example: "+16175551212"
curl -i -X POST \
  https://api.sbx.transmitsecurity.io/cis/v1/auth/password/reset/sms/otp \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "prev_reset_token": "string",
    "ignore_mfa": true,
    "phone_number": "+16175551212"
  }'

Responses

Bodyapplication/json
messagestringread-onlyrequired
Example: "SMS Sent"
Response
application/json
{
  "message": "SMS Sent"
}

Validate reset SMS OTP

Request

Validate a reset password OTP.

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

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

Responses

Bodyapplication/json
resultstringrequired

Reset token to be used when sending a reset request (/auth/password/reset)

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

Start reset by password

Request

Validates the current password and returns a reset token, which enables changing the user`s password

Bodyapplication/jsonrequired
prev_reset_tokenstring

Reset token that contains mfa_required as true. Should be passed when initiating a second factor authentication, in case MFA is required for password reset flows.

usernamestring

The user's username. Pass either username or email, but not both.

emailstring

The user's primary email address. Pass either username or email, but not both.

phone_numberstring

The user's primary phone number. Pass only one of username, email, or phone_number, but not both.

passwordstringrequired

The user's current password

client_idstringrequired
curl -i -X POST \
  https://api.sbx.transmitsecurity.io/cis/v1/auth/password/reset/password/validate \
  -H 'Content-Type: application/json' \
  -d '{
    "prev_reset_token": "string",
    "username": "string",
    "email": "string",
    "phone_number": "string",
    "password": "string",
    "client_id": "string"
  }'

Responses

Bodyapplication/json
resultstringrequired

Reset token to be used when sending a reset request (/auth/password/reset)

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

Reset password

Request

Resets a user's password

Bodyapplication/jsonrequired
reset_tokenstringrequired

Valid reset_token generated from the password login call or by initiating a password reset flow

new_passwordstringrequired

The new password

redirect_uristring

Redirect URI for redirecting the client after a successful password change

resourcestring

Resource to access after successful password change

require_mfaboolean

Require multi-factor authentication for this authentication request.

Default false
Example: true
curl -i -X POST \
  https://api.sbx.transmitsecurity.io/cis/v1/auth/password/reset \
  -H 'Content-Type: application/json' \
  -d '{
    "reset_token": "string",
    "new_password": "string",
    "redirect_uri": "string",
    "resource": "string",
    "require_mfa": true
  }'

Responses

Bodyapplication/json
messagestringread-onlyrequired
Example: "Password changed successfully"
urlstringread-onlyrequired

URL to start the authorization flow with the new password

emailstringread-onlyrequired

User email to which the notification will be sent

Response
application/json
{
  "message": "Password changed successfully",
  "url": "string",
  "email": "string"
}

Validate password

Request

Validates a new password according to the requesting application's password policy. The validation includes checking the password complexity (such as minimum length and character requirements) and password history (i.e., that the same password wasn't used too recently). This can be used before updating a user's password to first check that the password they chose is valid and if not, provide feedback to the user.

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

Security
ClientAccessToken
Bodyapplication/jsonrequired
emailstring

Email of the user who provided the password. Used to identify the user to check password history.

phone_numberstring

Phone number of the user who provided the password. Used to identify the user to check password history.

usernamestring

Username of the user who provided the password. Used to identify the user to check password history.

passwordstringrequired

Password to validate

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

Responses

Bodyapplication/json
resultobjectrequired
result.​valid_passwordbooleanrequired

Boolean describing if the password is valid for this app and/or user

result.​errorsArray of objectsrequired

List of issues found with the given password, if validation fails

result.​errors[].​codestringrequired

Validation issue with given password

result.​errors[].​messagestringrequired

Description of the specific problem with the given password

Response
application/json
{
  "result": {
    "valid_password": true,
    "errors": [ … ]
  }
}

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
}