Login

Authenticate user. When the user's mfa_mode is off, the response includes authenticated session artifacts and the refresh token cookie is scoped to the provided X-App-ID (e.g. refresh_token_web-app). When mfa_mode is email, phone, or totp (with TOTP enrolled), the response is a pre-auth challenge (MFAResponse) and no authenticated access token or refresh cookie is issued until /v1/verify-2FA succeeds. If mfa_mode is totp but TOTP is not enrolled—especially for Internal-role users—a challenge is returned with credential_type totp_setup_required and a localized message until enrollment completes.

curl -X POST "https://example.com/v1/authenticate" \  -H "Content-Type: application/json" \  -d '{    "username": "user@example.com",    "password": "secure_password"  }'

{
  "access_token": "string",
  "expires_in": 0,
  "idle_timeout_seconds": 0,
  "user_id": "a169451c-8525-4352-b8ca-070dd449a1a5"
}

{
  "code": "auth.unauthorized",
  "message": "Invalid credentials"
}

{
  "code": "auth.account_locked",
  "message": "Account locked for 15 minutes"
}