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 nurse users using GraphQL.

Steps​

1. Setup OTP Authentication​

info

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

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

query NurseSetupOtpAuth($forceSetup: Boolean) {
  nurseSetupOtpAuth(forceSetup: $forceSetup) {
    otpQrCode
    otpSecretText
    otpUri
    id
    otpEnabled 
    otpStatus
  }
}

Variables:

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

Response

{
  "data": {
    "nurseSetupOtpAuth": {
      "otpQrCode": "svg_string_qr_code",
      "otpSecretText": "secret",
      "otpUri": "otpauth://totp/...",
      "id": "nurse_id",

      "otpEnabled": false,
      "otpStatus": "initiated"
    }
  }
}

2. Display OTP QR Code​

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

3. Complete OTP setup​

Once the nurse 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 CompleteNurseOtpSetup($id: ID!, $input: CompleteNurseOtpSetupInput!) {
  completeNurseOtpSetup(id: $id, input: $input) {
    result {
      id
      otpEnabled
      otpStatus
    }
  }
}

Variables:

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

Response

{
  "data": {
    "completeNurseOtpSetup": {
      "result": {
        "id": "nurse_id",
        "otpEnabled": true,
        "otpStatus": "enabled"
      }
    }
  }
}

4. Complete OTP Setup​

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

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

5. Sign In with OTP​

When the nurse 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 NurseSignIn($email: String!, $password: String!) {
  nurseSignIn(email: $email, password: $password) {
    token
    id    
  }
}

Variables:

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

Response will include token with prefix otp_.

{
  "data": {
    "nurseSignIn": {
      "token": "otp_SomeOtpToken",
      "id": "nurse_id"
    }
  }
}

5b. Verify Sign-In with OTP Code​

To complete the sign-in process, the nurse 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 NurseVerifySignInWithOtpCode($otpCode: String!, $signInOtpToken: String!) {
  nurseVerifySignInWithOtpCode(otpCode: $otpCode, signInOtpToken: $signInOtpToken) {
    token
    id
  }
}

Variables:

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

Response

{
  "data": {
    "nurseVerifySignInWithOtpCode": {    
      "token": "login_token",
      "id": "nurse_id"
    }
  }
}

Conclusion​

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

Flow Diagram​