OTP Login

BioT supports One-Time Password (OTP) authentication through its REST API, offering a secure and user-friendly way to log in. This guide provides step-by-step instructions for enabling OTP functionality and performing OTP-based logins.

🚧

Prerequisite: Enable SMS

To implement OTP login, the first step is enabling SMS services. SMS is the communication channel through which OTP codes are delivered to users.

For detailed instructions, refer to the Sending and Receiving SMS Messages documentation.

Once SMS services are set up, you can integrate OTP functionality into your solution.

Note:

• This feature is available only via API integration.
• You can use this sample plugin to automatically configure users for OTP login during registration through BioT’s portal.
• After setting up OTP login for users, customize your application’s login pages to integrate with the login APIs outlined in the steps below.

Step 1: Registering Users for OTP Login

To enable OTP login for a user, you need to set an OTP authentication method for that user. This is done by setting the _credentialType attribute with the value "OTP" during the registration process. This requirement applies to the registration of patients, caregivers, or organization users.

Instructions:

1. Include the _credentialType: "OTP" attribute in your request payload while registering the user.
2. Ensure that you refer to the API documentation for details on the required fields and processes for registering patients, caregivers, or organization users.

🚧

Important Notice

The _credentialType attribute cannot be added or modified using a patch request for an existing user. This attribute is only set during the initial registration.

Step 2: Generating an OTP Code

Once the user is registered with OTP credentials, you can generate a one-time password for them. The OTP generation API should be called when a user initiates the login process and requests to log in using OTP. This typically happens after the user provides their registered phone number in your login interface.

To generate the OTP code, call the following API endpoint:

Endpoint:
POST /{{API_URL}}/ums/v2/users/otp/generate

Request Body:

{
  "phone": "+12345678901"
}

A successful request returns a JSON object containing the requestId and a partially masked phone number for security.

{
  "requestId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "phone": "******8901"
}

• requestId: A unique identifier for the OTP request. Save this value for the next step.
• phone: The phone number associated with the OTP request is partially obscured for privacy.

Additionally, the user will receive an SMS containing the OTP code. For example:
“Hello, your user verification code is 649551.”

Step 3: Logging In with OTP

After obtaining the OTP code and the requestId from the previous step, use them to complete the login process.

Endpoint:
POST /{{API_URL}}/ums/v2/users/otp/login

Request Body:

{
  "requestId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "code": "649551"
}

A successful login returns a JSON object containing user details, access tokens, and any additional requirements.

{
  "userId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "ownerOrganizationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "accessJwt": {
    "token": "string",
    "expiration": "2024-12-03T12:48:30.979Z"
  },
  "refreshJwt": {
    "token": "string",
    "expiration": "2024-12-03T12:48:30.979Z"
  },
  "mfaRequired": true,
  "mfaExpiration": "2024-12-03T12:48:30.979Z",
  "passwordResetRequired": true,
  "phone": "string"
}

Post-Login Actions

Use the accessJwt token for authorized API calls.

If required, use refreshJwt to renew the session when the access token expires.

Customizing OTP settings

BioT’s OTP functionality offers configurable options to tailor the feature to your needs. The following settings are configurable:

1. Passcode Validity: Default duration is 2 minutes.
2. Code Length: Default is 6 digits.
3. SMS Message Content: Default text is: “Hello, your user verification code is XXXXXX.”

To modify any of these settings, please contact our support team and provide the required configuration details.