Authentication & Login API

The authentication endpoints cover account registration, click-based human verification, OAuth2-compatible password login, TOTP two-factor challenges and verification, password reset, and email verification. The base path is /api/v1.

Endpoints Overview

Tokens and Sessions

A successful login returns a JWT to send as Authorization: Bearer <token>.

Human Verification (Captcha)

When enable_captcha is on (default false), registration, password login, and password recovery must carry a captcha proof.

1. Get a challenge

GET /api/v1/captcha

{
  "code": 0,
  "data": {
    "captcha_id": "c62040db-91fa-4ff8-9125-5e3681428256",
    "challenge": "{\"target_text\": \"Please click the red circle\", \"image\": \"data:image/png;base64,...\"}",
    "prompt": "captcha_click_prompt",
    "expires_in": 300
  },
  "msg": "success"
}

challenge is a JSON string you must parse yourself, and expires_in is 300 seconds.

2. Submit the click for a proof token

POST /api/v1/captcha/click
Content-Type: application/json

{
  "captcha_id": "c62040db-91fa-4ff8-9125-5e3681428256",
  "challenge": "{\"target_text\": \"Please click the red circle\", \"image\": \"data:image/png;base64,...\"}",
  "clicked_option": "red_circle",
  "elapsed_ms": 1340,
  "pointer": [
    {"x": 105.5, "y": 80.2, "t": 1200, "event": "move"},
    {"x": 108.0, "y": 82.0, "t": 1340, "event": "move"}
  ]
}

{
  "code": 0,
  "data": {
    "captcha_id": "c62040db-91fa-4ff8-9125-5e3681428256",
    "captcha_token": "proof-token-string"
  },
  "msg": "success"
}

The proof is single-use: the same captcha_id + captcha_token cannot be exchanged for a second login.

Password Login and Two-Factor Authentication

1. Submit credentials

Standard OAuth2 form encoding (application/x-www-form-urlencoded, not JSON):

POST /api/v1/login/access-token
Content-Type: application/x-www-form-urlencoded

username=alice@example.com&password=SecurePassword123!&captcha_id=c62040db-...&captcha_token=proof-token-string

The pre-login check order decides which error you see:

1. Password login disabled by the deployment (sso_enabled = true with sso_allow_password_login = false) → 400 / 6306.
2. Account locked → 400 / 5300, with data.lockout_seconds for the remaining wait.
3. Wrong password → 400 / 2003, with data.remaining_attempts; reaching max_login_attempts (default 5) locks the account for lockout_duration_minutes (default 15) and returns 5300.
4. Inactive or pending account → 400 / 2004 (a pending approval_status reports pending approval).
5. TOTP enabled → returns requires_totp (below).
6. Deployment requires TOTP (require_totp = true) but the user has not enrolled → returns requires_totp_setup.
7. Email verification on (email_verification defaults to true) and the user unverified (superusers excepted) → 400 / 5004 with data.email.

Direct login success (200 OK)

{
  "code": 0,
  "data": { "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", "token_type": "bearer" },
  "msg": "Login successful"
}

Two-factor challenge

When TOTP is enabled the server does not issue a full token; it returns a temp token valid for 5 minutes:

{
  "code": 0,
  "data": { "requires_totp": true, "temp_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." },
  "msg": "totp_required"
}

Enrollment required first

When the deployment sets require_totp and the account has not enrolled, the server returns a temp token valid for 30 minutes so the client can call /api/v1/totp/setup first:

{
  "code": 0,
  "data": { "requires_totp_setup": true, "temp_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." },
  "msg": "totp_setup_required"
}

Forced password change

When the password has expired or an administrator forced a change, a full token is still issued but flagged:

{
  "code": 0,
  "data": {
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "token_type": "bearer",
    "force_password_change": true,
    "reason": "expired"
  },
  "msg": "Login successful. You must change your password before continuing."
}

reason is expired (password expired) or force (administrator-forced). Send the user to POST /api/v1/users/me/change-password.

2. Verify the TOTP code and finish signing in

POST /api/v1/login/verify-totp
Content-Type: application/x-www-form-urlencoded

temp_token=temp-jwt-token-string&code=123456&is_backup_code=false

Every field is a form field; sending a JSON body returns 422.

On success the forced-password-change rules are applied exactly as in login, and the response is:

{
  "code": 0,
  "data": { "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", "token_type": "bearer" },
  "msg": "Two-factor authentication verified successfully"
}

Failure paths:

A backup recovery code is consumed on first successful use, and the remaining count is written to the audit log.

3. Log out

POST /api/v1/logout
Authorization: Bearer YOUR_TOKEN

Blacklists the current token; the response has data: null and msg set to Logout successful. The client must sign in again afterwards.

Registration and Email Verification

1. Register a new account

POST /api/v1/register
Content-Type: application/json

{
  "username": "bob",
  "email": "bob@example.com",
  "password": "StrongPassword123!",
  "locale": "en",
  "terms_accepted": true,
  "captcha_id": "c62040db-...",
  "captcha_token": "proof-token-string"
}

The outcome depends on site settings; msg and the account state change with them:

Failure paths: duplicate username 5002; duplicate email 5003; password outside the policy 1001 (data.errors.password lists the reasons); open registration disabled 5000; missing or failed captcha 5302/5303.

2. Send a verification email

POST /api/v1/send-verification
Content-Type: application/json

{ "email": "bob@example.com", "purpose": "register" }

Behavior differs by purpose:

• purpose = register: the user for that email must exist and be unverified; a missing user returns 400 / 4000 and an already-verified user returns 400 / 1001.
• purpose = reset_password: always returns success to prevent enumeration; an email is sent when the user exists.

There is a 60-second cooldown per email address and purpose; a repeat inside it returns 400 / 5008 with data.remaining_seconds. When SMTP is disabled the response is 400 / 5007. Emails are sent by a background task, so the response only means “queued”.

3. Verify the email with the 6-digit code

POST /api/v1/verify-email
Content-Type: application/json

{ "email": "bob@example.com", "code": "839201", "purpose": "register" }

With purpose = register the user's email_verified is set to true.

{ "code": 0, "data": { "verified": true, "email": "bob@example.com" }, "msg": "Email verified successfully" }

An incorrect or already-consumed code returns 400 / 5005.

4. Verify the email through the email link

GET /api/v1/verify?token=email-verification-token-string

token is a query parameter. An invalid or expired token returns 400 / 5006; otherwise the response matches the code-based flow.

5. Resend the registration verification email

POST /api/v1/resend-verification
Content-Type: application/json

{ "email": "bob@example.com" }

Unlike send-verification with the register purpose, this endpoint also returns success for an unknown address (anti-enumeration), but an already-verified address returns 400 / 1001. The same 60-second cooldown (5008) and SMTP switch (5007) apply.

Password Recovery and Reset

1. Start password recovery

POST /api/v1/forgot-password
Content-Type: application/json

{ "email": "alice@example.com" }

To prevent email enumeration the endpoint always returns success regardless of whether the address exists (msg is If the email exists, a password reset link has been sent). Two cases still leak: SMTP disabled returns 400 / 5007, and a repeat inside the 60-second cooldown returns 400 / 5008. That is a deliberate availability-over-privacy tradeoff — plan for it.

2. Confirm the reset

Two mutually exclusive methods; provide at least one (neither gives 422):

POST /api/v1/reset-password
Content-Type: application/json

{ "email": "alice@example.com", "code": "839201", "new_password": "NewStrongPassword456!" }

POST /api/v1/reset-password
Content-Type: application/json

{ "token": "reset-token-string", "new_password": "NewStrongPassword456!" }

A successful reset also clears the account's consecutive failure count and lockout time (failed_login_attempts, locked_until), so a locked-out user can recover immediately by resetting the password.

Failure paths: invalid code/token 400 / 5005; user not found 400 / 4000; new password outside the policy 400 / 1001.

Where TOTP and SSO Continue

The login flow only issues and verifies challenges; everything else lives on other pages:

Error Codes

Related Documentation

• TOTP API — enrollment, backup codes, and status for two-factor authentication
• SSO API — provider configuration, login redirect, and callbacks
• Users API — change password, password status, and account deletion
• API Quick Start — call an Agent directly with an API key