Admin Login
Authenticate admin user with Internal role. 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. When mfa_mode requires MFA, the initial response is challenge-only until /v1/verify-2FA succeeds. Internal users with mfa_mode totp and no TOTP secret receive credential_type totp_setup_required until TOTP enrollment completes.
/v1/authenticate/adminIn: header
Header Parameters
Application identifier. Must be a value from the configured whitelist (e.g. web-app, admin-app, configurator-app). When provided, the refresh token cookie is scoped per application to prevent cross-app token collisions. If a whitelist is configured and the value is not in it, the request is rejected with 400.
Device identifier for device binding.
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/v1/authenticate/admin" \ -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.unauthorized_role",
"message": "User is not authorized to perform this operation"
}{
"code": "auth.account_locked",
"message": "Account locked for 15 minutes"
}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.
Next Page