Standard Authentication

This section covers the standard authentication operations available in the GraphQL Main API.

Queries

isUsernameExists

Check if a username is already taken.

query IsUsernameExists($username: String!) {
  isUsernameExists(username: $username)
}

Arguments:

• username (String!): The username to check

Returns:

• Boolean: true if the username exists, false otherwise

Example Input:

query {
  isUsernameExists(username: "johndoe123")
}

Example Output:

{
  "data": {
    "isUsernameExists": true
  }
}

isEmailExists

Check if an email is already registered.

query IsEmailExists($email: String!) {
  isEmailExists(email: $email)
}

Arguments:

• email (String!): The email to check

Returns:

• Boolean: true if the email exists, false otherwise

Example Input:

query {
  isEmailExists(email: "johndoe@example.com")
}

Example Output:

{
  "data": {
    "isEmailExists": true
  }
}

Mutations

requestLoginLookup

Initiate a login process. This will send a verification code to the user's email.

mutation RequestLoginLookup($input: RequestLoginLookupInput!) {
  requestLoginLookup(input: $input) {
    status
    message
    userId
    errorMessage
  }
}

Input:

input RequestLoginLookupInput {
  email: String!        // The user's email address to which the lookup code will be sent for verification purposes
  recaptcha: String!    // The reCAPTCHA token to validate that the request is being made by a human
  fingerprint: String   // Optional device fingerprint for additional security
}

Returns:

type RequestLookupResponse {
  status: ResponseStatus!  // SUCCESS or ERROR
  message: String          // Success message if applicable
  userId: String           // User ID for the verification step
  errorMessage: String     // Error message if status is ERROR
}

Example Input:

mutation {
  requestLoginLookup(
    input: {
      email: "johndoe@example.com"
      recaptcha: "03AGdBq24tJhg..."
      fingerprint: "device-fingerprint-123"
    }
  ) {
    status
    message
    userId
    errorMessage
  }
}

Example Output:

{
  "data": {
    "requestLoginLookup": {
      "status": "SUCCESS",
      "message": "Verification code sent to your email",
      "userId": "user_12345abcde",
      "errorMessage": null
    }
  }
}

verifyLoginLookup

Complete the login process by verifying the code sent to the user's email.

mutation VerifyLoginLookup($input: VerifyLoginLookupInput!) {
  verifyLoginLookup(input: $input) {
    status
    user {
      id
      username
      email
      # other user fields
    }
    errorMessage
    onBoardingCompleted
    newUser
    mfaPhoneHint
    mfaType
    unlocksAt
  }
}

Input:

input VerifyLoginLookupInput {
  userId: String!    // The unique identifier of the user attempting to log in
  code: String!      // The lookup code sent to the user's email for verification
  recaptcha: String! // The reCAPTCHA token to validate that the request is being made by a human
}

Returns:

type LoginResponse {
  status: ResponseStatus!        // SUCCESS or ERROR
  user: UserModel                // The authenticated user's details
  errorMessage: String           // Error message if status is ERROR
  onBoardingCompleted: Boolean   // Whether the user has completed onboarding
  newUser: Boolean               // Whether this is a new user
  mfaPhoneHint: String           // If MFA is enabled, a hint about the phone number
  mfaType: MfaType               // Type of MFA if required for login
  unlocksAt: Date                // When user is no longer restricted from making this request
}

Note: Upon successful authentication, the accessToken and refreshToken are set as HTTP cookies and are not directly returned in the response body.

Example Input:

mutation {
  verifyLoginLookup(
    input: {
      userId: "user_12345abcde"
      code: "123456"
      recaptcha: "03AGdBq24tJhg..."
    }
  ) {
    status
    user {
      id
      username
      email
    }
    errorMessage
    onBoardingCompleted
    newUser
    mfaPhoneHint
    mfaType
    unlocksAt
  }
}

Example Output:

{
  "data": {
    "verifyLoginLookup": {
      "status": "SUCCESS",
      "user": {
        "id": "user_12345abcde",
        "username": "johndoe123",
        "email": "johndoe@example.com"
      },
      "errorMessage": null,
      "onBoardingCompleted": true,
      "newUser": false,
      "mfaPhoneHint": null,
      "mfaType": null,
      "unlocksAt": null
    }
  }
}

requestRegisterLookup

Initiate a registration process. This will send a verification code to the user's email.

mutation RequestRegisterLookup($input: RequestRegisterLookupInput!) {
  requestRegisterLookup(input: $input) {
    status
    message
    userId
    errorMessage
  }
}

Input:

input RequestRegisterLookupInput {
  username: String!               // The username of the user to be registered
  email: String!                  // The user's email address for verification purposes
  recaptcha: String!              // The reCAPTCHA token for validation
  agreedToTerms: Boolean!         // Confirmation that user has agreed to terms of service
  receiveMarketingOffers: Boolean! // User's preference for marketing communications
  fingerprint: String             // Optional device fingerprint for additional security
  referrerUserId: String          // Optional referrer user ID
  referrerUsername: String        // Optional referrer username
  promoCode: String               // Optional promotion code
}

Returns:

type RequestLookupResponse {
  status: ResponseStatus!  // SUCCESS or ERROR
  message: String          // Success message if applicable
  userId: String           // Temporary user ID for the verification step
  errorMessage: String     // Error message if status is ERROR
}

Example Input:

mutation {
  requestRegisterLookup(
    input: {
      username: "johndoe123"
      email: "johndoe@example.com"
      recaptcha: "03AGdBq24tJhg..."
      agreedToTerms: true
      receiveMarketingOffers: false
      fingerprint: "device-fingerprint-123"
      referrerUsername: "existinguser"
    }
  ) {
    status
    message
    userId
    errorMessage
  }
}

Example Output:

{
  "data": {
    "requestRegisterLookup": {
      "status": "SUCCESS",
      "message": "Verification code sent to your email",
      "userId": "temp_user_12345abcde",
      "errorMessage": null
    }
  }
}

verifyRegisterLookup

Complete the registration process by verifying the code sent to the user's email.

mutation VerifyRegisterLookup($input: VerifyRegisterLookupInput!) {
  verifyRegisterLookup(input: $input) {
    status
    user {
      id
      username
      email
      # other user fields
    }
    errorMessage
    onBoardingCompleted
    newUser
    mfaPhoneHint
    mfaType
    unlocksAt
  }
}

Input:

input VerifyRegisterLookupInput {
  email: String!       // The email address to which the lookup code was sent
  code: String!        // The verification code sent to the user's email
  recaptcha: String!   // The reCAPTCHA token for validation
}

Returns:

type LoginResponse {
  status: ResponseStatus!        // SUCCESS or ERROR
  user: UserModel                // The newly registered user's details
  errorMessage: String           // Error message if status is ERROR
  onBoardingCompleted: Boolean   // Whether the user has completed onboarding
  newUser: Boolean               // Whether this is a new user
  mfaPhoneHint: String           // If MFA is enabled, a hint about the phone number
  mfaType: MfaType               // Type of MFA if required for login
  unlocksAt: Date                // When user is no longer restricted from making this request
}

Example Input:

mutation {
  verifyRegisterLookup(
    input: {
      email: "johndoe@example.com"
      code: "123456"
      recaptcha: "03AGdBq24tJhg..."
    }
  ) {
    status
    user {
      id
      username
      email
    }
    errorMessage
    onBoardingCompleted
    newUser
    mfaPhoneHint
    mfaType
    unlocksAt
  }
}

Example Output:

{
  "data": {
    "verifyRegisterLookup": {
      "status": "SUCCESS",
      "user": {
        "id": "user_12345abcde",
        "username": "johndoe123",
        "email": "johndoe@example.com"
      },
      "errorMessage": null,
      "onBoardingCompleted": false,
      "newUser": true,
      "mfaPhoneHint": null,
      "mfaType": null,
      "unlocksAt": null
    }
  }
}

signOut

Log out the current user by revoking their refresh token.

mutation SignOut {
  signOut
}

Arguments: None (uses the refresh token from cookies)

Returns:

• Boolean: true if the sign-out was successful, false otherwise

Example Input:

mutation {
  signOut
}

Example Output:

{
  "data": {
    "signOut": true
  }
}

generateTokenForExternalSystem

Generate a token for use with external systems.

mutation GenerateTokenForExternalSystem(
  $input: GenerateTokenForExternalSystemInput!
) {
  generateTokenForExternalSystem(input: $input) {
    status
    token
    errorMessage
  }
}

Input:

input GenerateTokenForExternalSystemInput {
  externalSystemId: String!                 // The external system ID (must be a valid MongoDB ID)
  externalSystemType: ExternalSystemType     // The type of external system (defaults to BP)
}

Returns:

type GenerateTokenForExternalSystemResponse {
  status: ResponseStatus!  // SUCCESS or ERROR
  token: String            // Generated token for the external system
  errorMessage: String     // Error message if status is ERROR
}

Example Input:

mutation {
  generateTokenForExternalSystem(
    input: {
      externalSystemId: "611f9e7beb4c9d3a2a8b4567"
      externalSystemType: BP
    }
  ) {
    status
    token
    errorMessage
  }
}

Example Output:

{
  "data": {
    "generateTokenForExternalSystem": {
      "status": "SUCCESS",
      "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
      "errorMessage": null
    }
  }
}

revokeSession

Revoke a specific user session.

mutation RevokeSession($input: RevokeSessionInput!) {
  revokeSession(input: $input)
}

Input:

input RevokeSessionInput {
  id: String!  // The session ID to revoke
}

Returns:

• Boolean: true if the session was successfully revoked, false otherwise

Example Input:

mutation {
  revokeSession(input: { id: "session_12345abcde" })
}

Example Output:

{
  "data": {
    "revokeSession": true
  }
}

revokeAllButCurrentSessions

Revoke all user sessions except the current one. This is useful for security purposes when a user wants to log out from all other devices.

mutation {
  revokeAllButCurrentSessions
}

Authentication Requirements:

• Requires a valid access token cookie
• Requires USER role
• If MFA device removal is enabled for the user, the user must be verified through MFA before using this endpoint

Returns:

• Boolean: true if the sessions were successfully revoked, false otherwise

Example Input:

mutation {
  revokeAllButCurrentSessions
}

Example Output:

{
  "data": {
    "revokeAllButCurrentSessions": true
  }
}

Error Responses:

• UNAUTHORIZED_ACCESS: If the user has MFA device removal enabled and hasn't completed MFA verification
• NOT_FOUND: If the user associated with the token cannot be found