Login with passwords
Transmit supports authenticating users with a username (or email) and password, which allows migrating customers from passwords to a passwordless solution. For example, you can provide your customers with a temporary password to use for their first login to Transmit. They can then set their own password to use for subsequent logins. You can allow them to reset a forgotten password via email or SMS flows, or to change their password upon expiration or whenever needed.
Step 1: Create redirect URI
Create the redirect endpoint that will receive an authorization code when users login with their username and password. This code will later be exchanged for an ID and access token. The redirect URI should accept code
as a query parameter. For example, if https://domain.com/verify
is your redirect URI, then Transmit will redirect to https://domain.com/verify?code=123abc
.
Step 2: Add redirect URI to app
Add the redirect URI (e.g., https://domain.com/verify
) as an allowed redirect URI for your Transmit application. This will also be the redirect_uri
that you'll need to pass in the login request.
From the Admin Portal under Applications, click on your application to edit your application settings and add this URI under Redirect URIs. If you don't already have an application, create a new application.
Step 3: Configure auth method
You can configure the Passwords authentication method from the Authentication page of the Admin Portal or using the Login Preferences API by sending a request like the one below. This can be used to set:
-
Password complexity requirements (
passwordComplexity
) and minimum length (passwordMinLength
) -
Password expiry time (
passwordExpiresIn
) -
Allowed reuse of old passwords (
blockPreviousPasswords
) -
Allowed password attempts (
maxPasswordFailures
) and lockout duration (passwordSuspensionDuration
) -
Password reset link and code expiry time (
resetValidityMinutes
)
Note:
Make sure you have a valid client access token to authorize the request. If not, you'll need to get one. More
curl -i -X PUT \
https://api.transmitsecurity.io/cis/loginPreferences/ap4oFkD56FT3O9MEdbD-S/authMethods \
-H 'Authorization: Bearer 91827321837bdfjf' \
-H 'Content-Type: application/json' \
-d '{
"password": {
"resetValidityMinutes": 15,
"passwordComplexity": 2,
"passwordMinLength": 6,
"blockPreviousPasswords": 5,
"passwordExpiresIn": 90,
"maxPasswordFailures": 3,
"passwordSuspensionDuration": 2
}
}'
Step 4: Register password
Passwords can be registered in several ways:
- For an existing, logged-in user using the /v1/users/me/password-credentials endpoint
- When creating a new user using the /v1/users endpoint, which requires either setting a username or a primary email to use for password authentication.
- When creating a new user using the /v1/auth/password/register , which creates a temporary password that they'll need to change upon their first login.
For example, to create a temporary password using the last option, send a registration request with their username and an initial password. The access token that authorizes the request will determine for which application the user is created (see Get client access tokens).
Note
The username should correspond to a representation of the user in your app. It will be set as their username
(an app-level attribute) in their user profile and must be unique per application. The username is not associated with the email or phone number attributes on their profile, which are set on a tenant level. You can search users by username via API.
This example creates a new user, where the username is user@email.com and the password is ABC123:
curl -i -X POST \
https://api.transmitsecurity.io/cis/v1/auth/password/register \
-H 'Authorization: Bearer 91827321837bdfjf' \
-H 'Content-Type: application/json' \
-d '{
"username": "user@email.com",
"password": "ABC123"
}'
Step 5: Authenticate user
When users enter their username and password, they should be validated by sending a login request like the one below. The redirect_uri
is the one added in Step 2, and the client_id
can be found in the application settings.
curl -i -X POST \
https://api.transmitsecurity.io/cis/v1/auth/password/login \
-H 'Content-Type: application/json' \
-d '{
"username": "user@email.com",
"password": "ABC123",
"client_id": "c35ab2a.xVShlOVGsUMh3Cqk73K1O.transmit",
"redirect_uri": "https://domain.com/verify"
}'
If the provided credentials are valid, one of the following responses will be returned:
-
A
200
response that contains a URL (result.url
) like below. Your client should send a GET request to this URL. This will redirect the browser to your redirect URI with the code that you'll exchange for user tokens in Step 6 .
{
"result": {
"url": "https://api.transmitsecurity.io/cis/oidc/auth?client_id..."
}
}
-
A
403
response that contains a reset token (reset_token
) like below. When this occurs (e.g., when a password expires or they attempted to log in with their initial password), users must update their password using Step 8 .
{
"reset_token": "eyJhbGciOiJIUzI1NiIsI...VDyvwfO11Lw",
"message": "temporary_password",
"error_code": 403
}
Step 6: Get user tokens
The URL returned upon successful authentication in Step 5 or reset in Step 8 redirects the browser to your redirect URI with a code
query parameter. Exchange this code for ID and access tokens by sending a /oidc/token request like the one below. Replace placeholders with the code you received earlier, your redirect URI, and your client credentials that can be found in your application settings from the Transmit Admin Portal.
curl -i -X POST \
https://api.transmitsecurity.io/oidc/token \
-H 'Content-Type: application/x-www-form-urlencoded' \
-d client_id=CLIENT_ID \
-d client_secret=CLIENT_SECRET \
-d code=CODE \
-d grant_type=authorization_code \
-d redirect_uri=REDIRECT_URI
Step 7: Start password reset
Users might need to change their password, such as when a password expires or is forgotten. To start any password reset flow, the user must authenticate to obtain a reset token, which will be used to reset the password in Step 8.
A password reset flow can be initiated in several ways:
- By logging in using an expired or temporary password
- By sending an email magic link
- By sending an SMS OTP
- By providing the current password
Note
The user must have a verified phone number for an SMS reset flow and a verified email for an email reset flow. For example, you can verify their phone number via SMS OTP and their email via email magic link.
The example below shows a request used to start a reset flow by sending an email magic link. The email will be sent to the verified email address of the user (corresponding to the email.value
field in the user's profile). When the user clicks the email link, the redirect_uri
will receive the reset token as the code
query param. The reset token is used to reset the password, as described in Step 8. For examples of additional reset flows, see Next Steps.
curl -i -X POST \
https://api.transmitsecurity.io/cis/v1/auth/password/reset/email/link \
-H 'Authorization: Bearer 91827321837bdfjf' \
-H 'Content-Type: application/json' \
-d '{
"username": "user@email.com",
"redirect_uri": "https://domain.com/update-password"
}'
Step 8: Reset password
After users enter a new password and you've obtained a reset token, send a reset request like the one below. Pass the reset_token
received in Step 5 or Step 7 and the new password.
Optionally, you can also pass a redirect URI (redirect_uri
) to login the user after successfully updating the password (see Step 6). If the URI isn't provided, the response will simply indicate whether the reset succeeded or failed.
curl --request POST \
--url https://api.transmitsecurity.io/cis/v1/auth/password/reset \
--header 'Content-Type: application/json' \
--data '
{
"reset_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6...fO11Lw",
"new_password": "EFG468!abc",
"redirect_uri": "https://domain.com/verify"
}
'
Next steps
Once you've completed a basic integration, here are some customizations and additional options to consider:
- Email customization
- Start reset via SMS OTP
-
Change passwords
Email customization
In the Admin Portal (Authentication > Passwords), you can customize the color of the reset email address that appears in the message of the default templates. The email message will use the application's logo and name.
Start reset via SMS OTP
You can initiate a password reset flow using an SMS OTP. The user must have a verified phone number.
-
Send a
start reset request
like the one below to send an SMS OTP to the specified user:
curl -i -X POST \ https://api.transmitsecurity.io/cis/v1/auth/password/reset/sms/otp \ -H 'Authorization: Bearer 91827321837bdfjf' \ -H 'Content-Type: application/json' \ -d '{ "phone_number": "+972111111111" }'
-
After the user enters the OTP, send a
validate request
like the one below. The response includes a
result
parameter containing the reset token for the password reset request (see Step 8 ).curl -i -X POST \ https://api.transmitsecurity.io/cis/v1/auth/password/reset/sms/otp/validate \ -H 'Authorization: Bearer 91827321837bdfjf' \ -H 'Content-Type: application/json' \ -d '{ "phone_number": "+972111111111", "passcode": "725927" }'
Change current password
A user can change their password as needed. Send a start reset request like the one below, with the client_id
, username
, and current password (password
). The response includes a result
parameter containing the reset token for the password reset request (see Step 8).
curl -i -X POST \
https://api.transmitsecurity.io/cis/v1/auth/password/reset/password/validate \
-H 'Authorization: Bearer 91827321837bdfjf' \
-H 'Content-Type: application/json' \
-d '{
"username": "user",
"password": "current_password",
"client_id": "c35ab2a.xVShlOVGsUMh3Cqk73K1O.transmit"
}'