Skip to main content

Setting Up OTP Authentication

This guide will walk you through the steps to set up OTP (One-Time Password) authentication for doctor users using GraphQL.

Steps​

1. Setup OTP Authentication​

info

The requests in this section require a valid doctor token. See Doctor Login for more information on how to obtain a token.

To initiate the OTP setup, the doctor needs to request OTP setup. This can be done using the following GraphQL query:

query DoctorSetupOtpAuth($forceSetup: Boolean) {
  doctorSetupOtpAuth(forceSetup: $forceSetup) {
    otpQrCode
    otpSecretText
    otpUri
    id
    otpEnabled 
    otpStatus
  }
}

Variables:

{
  "forceSetup": false // Set to true if you want to force setup
}

Response

{
  "data": {
    "doctorSetupOtpAuth": {
      "otpQrCode": "svg_string_qr_code",
      "otpSecretText": "secret",
      "otpUri": "otpauth://totp/...",
      "id": "doctor_id",
      "otpEnabled": false,
      "otpStatus": "initiated"
    }
  }
}

2. Display OTP QR Code​

The response from the doctorSetupOtpAuth query will include the otpQrCode, otpSecretText, and otpUri. Display the otpQrCode to the doctor so they can scan it using an OTP app like Google Authenticator (or any other OTP app).

3. Complete OTP setup​

Once the doctor has scanned the QR code and generated an OTP code, they need to verify it. This can be done using the following GraphQL mutation:

mutation CompleteDoctorOtpSetup($id: ID!, $input: CompleteDoctorOtpSetupInput!) {
  completeDoctorOtpSetup(id: $id, input: $input) {
    result {
      id
      otpEnabled
      otpStatus
    }
  }
}

Variables:

{
  "id": "doctor_id",
  "input": {
    "otpCode": "123456"
  }
}

Response

{
  "data": {
    "completeDoctorOtpSetup": {
      "result": {
        "id": "doctor_id",
        "otpEnabled": true,
        "otpStatus": "enabled"
      }
    }
  }
}

4. Complete OTP Setup​

If the OTP code is verified successfully, the OTP setup is complete. The doctor can now use OTP for authentication.

Next time the doctor signs in, you'll need to prompt them for the OTP code.

5. Sign In with OTP​

When the doctor signs in, they will receive an OTP token, if OTP is enabled, instead of the regular login token. They will need to verify and complete the sign in process using the OTP token and an OTP code.

5a. Normal Sign-In will return an OTP token.​

query DoctorSignIn($email: String!, $password: String!) {
  doctorSignIn(email: $email, password: $password) {
    token
    id    
  }
}

Variables:

{
  "email": "doctor@example.com", // Replace with the doctor's email
  "password": "password123" // Replace with the doctor's password
}

Response will include token with prefix otp_.

{
  "data": {
    "doctorSignIn": {
      "token": "otp_SomeOtpToken",
      "id": "doctor_id"
    }
  }
}

5b. Verify Sign-In with OTP Code​

To complete the sign-in process, the doctor must provide the OTP code from their OTP app. Use the OTP code and the token received in the previous step to verify the sign-in.

query DoctorVerifySignInWithOtpCode($otpCode: String!, $signInOtpToken: String!) {
  doctorVerifySignInWithOtpCode(otpCode: $otpCode, signInOtpToken: $signInOtpToken) {
    token
    id
  }
}

Variables:

{
  "otpCode": "123456",
  "signInOtpToken": "otp_SomeOtpToken" // Replace with the OTP token received during sign-in
}

Response

{
  "data": {
    "doctorVerifySignInWithOtpCode": {    
      "token": "login_token",
      "id": "doctor_id"
    }
  }
}

Conclusion​

By following these steps, doctor users can set up OTP authentication using GraphQL. Ensure to handle errors and edge cases appropriately in your frontend application.

Flow Diagram​