Authentication and MFA

External integration

The Altafid authentication flow supports plain login, refresh token rotation, and MFA setup or verification depending on the user's policy and current configuration.

POST /api/auth/login

Use email and password to initiate the session.

curl "https://api.altafid.dev.altafid.net/api/auth/login" \
  -X POST \
  -H "accept: application/json" \
  -H "content-type: application/json" \
  --data '{
    "username": "your-email@example.com",
    "password": "YourPassword123!"
  }'
StatusTokens returnedMeaning
LOGIN_SUCCESStoken, refreshTokenAuthentication completed. Use the token in the Authorization header for all subsequent requests.
MFA_SETUP_REQUIREDsetupTokenMFA policy requires setup before access is granted.
MFA_REQUIREDchallengeTokenPassword accepted; MFA verification still required.

A successful LOGIN_SUCCESS response body:

{
  "status": "LOGIN_SUCCESS",
  "token": "eyJhbGciOiJIUzI1NiJ9...",
  "refreshToken": "eyJhbGciOiJIUzI1NiJ9...",
  "username": "your-email@example.com",
  "tenantUuid": "T019A16FF372A70B5A9307B00CE85E4DA",
  "tenantStaffUuid": "TS019C06688AA57248B9EA5325DBDFC48E",
  "userUuid": "TS019C06688AA57248B9EA5325DBDFC48E",
  "tenantCode": "CONPAT_UAT",
  "userType": "TENANT_STAFF",
  "staffType": "ADMIN",
  "expiresIn": 3600000,
  "refreshExpiresIn": 604800000
}

POST /api/auth/refresh

Refresh tokens are rotated on every successful refresh. Store the new refresh token immediately.

{
  "refreshToken": "YOUR_REFRESH_TOKEN"
}
{
  "token": "NEW_ACCESS_TOKEN",
  "refreshToken": "NEW_REFRESH_TOKEN",
  "expiresIn": 3600,
  "refreshExpiresIn": 604800
}
Token lifetime note: the login response documents expiration in milliseconds, while refresh and MFA verification responses document expiration in seconds. Normalise these before computing renewal times in your integration.

Session helper endpoints

EndpointPurposeTypical use
POST /api/auth/logoutInvalidate or terminate the current session.Optional client logout flow.
POST /api/auth/validate-tokenCheck whether a JWT is still valid.Session diagnostics and support tooling.
POST /api/auth/change-passwordChange password for the authenticated user.User self-service account maintenance.
GET /api/auth/meReturn current user identity and tenant context.Session bootstrap and debugging.

MFA during login

If login returns MFA_REQUIRED, submit the challenge token and the six-digit TOTP code to complete login.

{
  "challengeToken": "CHALLENGE_TOKEN",
  "method": "TOTP",
  "otp": "123456"
}
{
  "success": true,
  "token": "ACCESS_TOKEN",
  "refreshToken": "REFRESH_TOKEN",
  "expiresIn": 3600,
  "refreshExpiresIn": 604800
}

MFA setup flow

If login returns MFA_SETUP_REQUIRED, use the short-lived setup token in the Authorization header for the setup endpoints.

POST /api/auth/mfa/setup/init

Authorization: Bearer SETUP_TOKEN

{
  "method": "TOTP"
}
{
  "method": "TOTP",
  "secret": "BASE32_SECRET",
  "otpauthUri": "otpauth://totp/Altafid:email@example.com?secret=..."
}

POST /api/auth/mfa/setup/confirm

Authorization: Bearer SETUP_TOKEN

{
  "method": "TOTP",
  "otp": "123456"
}
{
  "success": true,
  "challengeToken": "CHALLENGE_TOKEN"
}

After confirmation, call POST /api/auth/mfa/verify with the returned challenge token to obtain the final access and refresh tokens.

GET /api/auth/mfa/status

Returns whether MFA is enabled, whether it is locked, and the currently configured methods for the authenticated user.

{
  "mfaEnabled": true,
  "isLocked": false,
  "methods": [
    {
      "type": "TOTP",
      "label": "Authenticator App",
      "isActive": true,
      "failedAttempts": 0
    }
  ]
}
Failure cases to handle: invalid login credentials, expired refresh tokens, expired challenge or setup tokens, invalid OTP codes, and temporarily locked MFA methods after repeated failures.