Passwords

Download OpenAPI specification:Download

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.

Login with password

Authenticate a user with a password

Request
Request Body schema: application/json
required
username
string

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

email
string

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

phone_number
string

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

password
required
string

The user's password

client_id
required
string

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

redirect_uri
required
string

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.

resource
string

Resource URI the login is attempting to access.

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.

org_id
string

Organization ID, used for member login in B2B scenarios

Responses
200
401

When the username/email and password don't match or don't exist

403

When the user has to change the password

post/v1/auth/password/login
Request samples
application/json
{
  • "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": {
    },
  • "org_id": "string"
}
Response samples
application/json
{
  • "result": {
    }
}

Start reset by email link

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.

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

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_mfa
boolean

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

email
string

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

username
string

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

redirect_uri
required
string

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.

object

Texts, logo and color to render email template with

Responses
200
403

When the email of the user is not verified

404

When there is no user with the requested email as a primary email in the tenant

post/v1/auth/password/reset/email/link
Request samples
application/json
{
  • "prev_reset_token": "string",
  • "ignore_mfa": true,
  • "email": "string",
  • "username": "string",
  • "redirect_uri": "https://www.example.com/reset-password",
  • "email_content": {
    }
}
Response samples
application/json
{
  • "message": "Reset password email sent"
}

Start reset by Email OTP

Starts a password reset flow by sending an Email OTP

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

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_mfa
boolean

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

email
required
string

The user's primary email address

object

Texts, logo and color to render email template with

Responses
200
403

When the email of the user is not verified, a forbidden error will be returned

404

When there is no user with the requested email address as primary email address in the tenant

post/v1/auth/password/reset/email/otp
Request samples
application/json
{
  • "prev_reset_token": "string",
  • "ignore_mfa": true,
  • "email": "string",
  • "email_content": {
    }
}
Response samples
application/json
{
  • "message": "Email Sent"
}

Validate reset OTP Email

Validate a reset password OTP

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

Email address that the OTP was sent to

passcode
required
string

OTP to validate

Responses
200
403

When the provided OTP is expired or invalid

404

When the requested user does not exist

post/v1/auth/password/reset/email/otp/validate
Request samples
application/json
{
  • "email": "string",
  • "passcode": "string"
}
Response samples
application/json
{
  • "result": "string"
}

Start reset by SMS OTP

Starts a password reset flow by sending an SMS OTP

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

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_mfa
boolean

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

phone_number
required
string

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

Responses
200
403

When the phone number of the user is not verified, a forbidden error will be returned

404

When there is no user with the requested phone number as primary phone number in the tenant

post/v1/auth/password/reset/sms/otp
Request samples
application/json
{
  • "prev_reset_token": "string",
  • "ignore_mfa": true,
  • "phone_number": "+16175551212"
}
Response samples
application/json
{
  • "message": "SMS Sent"
}

Validate reset SMS OTP

Validate a reset password OTP

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

Responses
200
403

When the provided OTP is expired or invalid

404

When the requested user does not exist

post/v1/auth/password/reset/sms/otp/validate
Request samples
application/json
{
  • "phone_number": "string",
  • "passcode": "string"
}
Response samples
application/json
{
  • "result": "string"
}

Start reset by password

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

Request
Request Body schema: application/json
required
prev_reset_token
string

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.

username
string

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

email
string

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

phone_number
string

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

password
required
string

The user's current password

client_id
required
string
Responses
200
403

When the provided username, password or client_id are incorrect

post/v1/auth/password/reset/password/validate
Request samples
application/json
{
  • "prev_reset_token": "string",
  • "username": "string",
  • "email": "string",
  • "phone_number": "string",
  • "password": "string",
  • "client_id": "string"
}
Response samples
application/json
{
  • "result": "string"
}

Register passwordDeprecated

Creates a new user with a username and temporary password, which the user needs to reset immediately following this request.

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

The new user's username. This will be the identifier the user will use to authenticate.

password
required
string

The new user's temporary password

Responses
200
403
post/v1/auth/password/register
Request samples
application/json
{
  • "username": "string",
  • "password": "string"
}
Response samples
application/json
{
  • "message": "Password registered"
}

Reset password

Resets a user's password

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

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

new_password
required
string

The new password

redirect_uri
string

Redirect URI for redirecting the client after a successful password change

resource
string

Resource to access after successful password change

require_mfa
boolean
Default: false

Require multi-factor authentication for this authentication request.

Responses
200
400

When the new password doesn't meet the password complexity requirements

403
post/v1/auth/password/reset
Request samples
application/json
{
  • "reset_token": "string",
  • "new_password": "string",
  • "redirect_uri": "string",
  • "resource": "string",
  • "require_mfa": true
}
Response samples
application/json
{
  • "message": "Password changed successfully",
  • "url": "string"
}

Validate password

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.

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

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

phone_number
string

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

username
string

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

password
required
string

Password to validate

Responses
200
403

When the application does not have password auth method configured

post/v1/auth/password/validate
Request samples
application/json
{
  • "email": "string",
  • "phone_number": "string",
  • "username": "string",
  • "password": "string"
}
Response samples
application/json
{
  • "result": {
    }
}

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
}