Authentication, MFA & OTP

How to authenticate, handle multi-factor challenges, and manage sessions.

The login flow

Check MFA status (optional but recommended): POST /v1/onboarding/login/mfa/status.
Log in: POST /v1/onboarding/login/user → returns a JWT in data.
Use the token: send Authorization: Bearer <JWT_TOKEN> on protected calls.
Refresh when the token nears expiry: POST /v1/onboarding/auth/refresh.
Log out: POST /v1/onboarding/logout.

❗ Important

The email and password fields on login, password-reset and MFA-status calls are encrypted strings, not plaintext. The client-side encryption scheme and key management are To be confirmed with the platform team.

Logging in

POST /v1/onboarding/login/user
Content-Type: application/json
x-correlation-id: <UUID>

{
  "email": "<ENCRYPTED_EMAIL>",
  "password": "<ENCRYPTED_PASSWORD>"
}

{
  "data": "<JWT_TOKEN>",
  "success": true,
  "message": "Login successful",
  "timestamp": "2026-06-03T10:15:30.000Z"
}

The login response's data field is the access token. Profile and module entitlements (role, userName, email, id, modules) are available via GET /v1/onboarding/me.

Multi-factor authentication (MFA)

MFA uses time-based one-time passwords (TOTP). Call the status endpoint to discover whether a user must register a device:

{
  "MFAEnabled": false,
  "MFARegistrationEnabled": false
}

{
  "encodedSecret": "OZCVGSDDGFFGQ4KFN5YHOQSMGR3WMTDR",
  "qrCode": "<BASE64_PNG>",
  "MFAEnabled": true,
  "MFARegistrationEnabled": true
}

When registration is required, display the qrCode (a base64-encoded PNG) for the user to scan, then complete enrolment:

POST /v1/onboarding/login/mfa/register

{
  "username": "<ENCRYPTED_USERNAME>",
  "encodedSecret": "GJSEGMLVONHUMSRUJVLEQT3QJI4FK3ZY",
  "deviceName": "My Authenticator App",
  "initialCode": "575851",
  "overwrite": false
}

⚠️ Warning

Treat encodedSecret as a secret. Do not log it or persist it client-side beyond the registration step.

Email OTP

Independently of TOTP, the platform can issue one-time passwords by email:

POST /v1/onboarding/generateOtp — body { "mailID": "jane.doe@example.com" }.
POST /v1/onboarding/validateOtp — body { "mailID": "jane.doe@example.com", "otp": "339261" }.

SSO token exchange

For SSO integrations (e.g. Grafana), POST /v1/onboarding/token accepts an OAuth2-style application/x-www-form-urlencoded body:

POST /v1/onboarding/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&code=<AUTH_CODE>&redirect_uri=https://app.example.com/login/callback&client_id=<CLIENT_ID>&client_secret=<CLIENT_SECRET>

Session & profile endpoints

Endpoint	Auth	Purpose
`GET /v1/onboarding/me`	Bearer	Current user profile + modules.
`GET /v1/onboarding/userinfo`	Bearer	OIDC-style claims.
`POST /v1/onboarding/auth/refresh`	Cookie/none	Issue a fresh access token.
`POST /v1/onboarding/logout`	Bearer	End the session.
`POST /v1/onboarding/verify-invite-url`	Public	Validate an invite token before account setup.
`PATCH /v1/onboarding/users/password`	Public	Set/reset a password (encrypted fields).

💡 Tip

See full request/response details for each of these in the Authentication section of the API Reference.