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 )

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:

1. For an existing, logged-in user using the /v1/users/me/password-credentials endpoint
2. 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.
3. 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).

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

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.

1. Send a start reset request like the one below to send an SMS OTP to the specified user:
   Copy

   Copied

   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"
   }'

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

   Copied

   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"
}'