Dashboard Authentication

Password and TOTP authentication for dashboard access

Overview

The Dashboard Authentication API manages password and two-factor authentication (TOTP) for accessing the Codex-LB web dashboard and management APIs.

Dashboard authentication is separate from API key authentication. API keys are for proxy endpoints, while dashboard auth is for management endpoints.

GET /api/dashboard-auth/session

Get the current dashboard authentication session state.

Response

isPasswordConfigured · boolean

Whether a password has been set up

isPasswordVerified · boolean

Whether the current session has verified the password

isTotpConfigured · boolean

Whether TOTP 2FA is configured

isTotpVerified · boolean

Whether the current session has verified TOTP

isTotpRequiredOnLogin · boolean

Whether TOTP is required for dashboard access

Example Request

cURL

curl http://localhost:2455/api/dashboard-auth/session

Example Response

{
  "isPasswordConfigured": true,
  "isPasswordVerified": false,
  "isTotpConfigured": true,
  "isTotpVerified": false,
  "isTotpRequiredOnLogin": true
}

POST /api/dashboard-auth/password/setup

Set up the initial dashboard password. Can only be called once.

Request Body

password · string · required

Password to set. Must be at least 8 characters.

Response

Returns session state after successful setup. Sets dashboard_session cookie.

Example Request

cURL

curl -X POST http://localhost:2455/api/dashboard-auth/password/setup \
  -H "Content-Type: application/json" \
  -d '{"password": "your-secure-password"}'

POST /api/dashboard-auth/password/login

Authenticate with the dashboard password.

Request Body

password · string · required

Dashboard password

Response

Returns session state after successful login. Sets dashboard_session cookie.

Rate Limiting

Password login is rate-limited to 8 attempts per 60 seconds per IP address.

Example Request

cURL

curl -X POST http://localhost:2455/api/dashboard-auth/password/login \
  -H "Content-Type: application/json" \
  -d '{"password": "your-password"}'

POST /api/dashboard-auth/password/change

Change the dashboard password. Requires active password session.

Request Body

currentPassword · string · required

Current password for verification

newPassword · string · required

New password to set. Must be at least 8 characters.

Example Request

cURL

curl -X POST http://localhost:2455/api/dashboard-auth/password/change \
  -H "Content-Type: application/json" \
  -H "Cookie: dashboard_session=<session_id>" \
  -d '{"currentPassword": "old-password", "newPassword": "new-password"}'

DELETE /api/dashboard-auth/password

Remove the dashboard password. Requires active password session.

Removing the password disables all authentication. Anyone will be able to access the dashboard.

Request Body

password · string · required

Current password for confirmation

Example Request

cURL

curl -X DELETE http://localhost:2455/api/dashboard-auth/password \
  -H "Content-Type: application/json" \
  -H "Cookie: dashboard_session=<session_id>" \
  -d '{"password": "current-password"}'

POST /api/dashboard-auth/totp/setup/start

Start TOTP (two-factor authentication) setup. Requires active password session.

Response

secret · string

TOTP secret key in base32 format

qrCodeDataUrl · string

Data URL for QR code image to scan with authenticator app

setupToken · string

Token to use when confirming TOTP setup

Example Request

cURL

curl -X POST http://localhost:2455/api/dashboard-auth/totp/setup/start \
  -H "Cookie: dashboard_session=<session_id>"

Example Response

{
  "secret": "JBSWY3DPEHPK3PXP",
  "qrCodeDataUrl": "data:image/png;base64,iVBORw0KGgoAAAANS...",
  "setupToken": "temp_token_abc123"
}

POST /api/dashboard-auth/totp/setup/confirm

Complete TOTP setup by verifying a code from the authenticator app.

Request Body

setupToken · string · required

Setup token from /totp/setup/start

code · string · required

6-digit code from authenticator app

Example Request

cURL

curl -X POST http://localhost:2455/api/dashboard-auth/totp/setup/confirm \
  -H "Content-Type: application/json" \
  -H "Cookie: dashboard_session=<session_id>" \
  -d '{"setupToken": "temp_token_abc123", "code": "123456"}'

POST /api/dashboard-auth/totp/verify

Verify a TOTP code to complete dashboard login.

Request Body

code · string · required

6-digit code from authenticator app

Response

Returns session state after successful verification. Updates dashboard_session cookie.

Rate Limiting

TOTP verification is rate-limited to 8 attempts per 60 seconds per IP address.

Example Request

cURL

curl -X POST http://localhost:2455/api/dashboard-auth/totp/verify \
  -H "Content-Type: application/json" \
  -H "Cookie: dashboard_session=<session_id>" \
  -d '{"code": "123456"}'

POST /api/dashboard-auth/totp/disable

Disable TOTP two-factor authentication. Requires active password session.

Example Request

cURL

curl -X POST http://localhost:2455/api/dashboard-auth/totp/disable \
  -H "Cookie: dashboard_session=<session_id>"

POST /api/dashboard-auth/logout

Log out and invalidate the current dashboard session.

Example Request

cURL

curl -X POST http://localhost:2455/api/dashboard-auth/logout \
  -H "Cookie: dashboard_session=<session_id>"

Session Management

Session Cookie

Authenticated sessions are stored in a cookie named dashboard_session:

• HTTPOnly: Yes (not accessible via JavaScript)
• Secure: Yes (HTTPS only in production)
• SameSite: Lax
• Max-Age: 12 hours (43200 seconds)
• Encryption: AES-256-GCM

Session State

Each session tracks:

• password_verified - Whether password was authenticated
• totp_verified - Whether TOTP was verified (if enabled)

If TOTP is required (isTotpRequiredOnLogin: true), both password_verified and totp_verified must be true to access protected endpoints.

Error Codes

Code	Status	Description
authentication_required	401	Session invalid or not authenticated
invalid_credentials	401	Password incorrect
totp_required	401	TOTP verification needed
totp_invalid_code	400	TOTP code incorrect
password_already_configured	409	Password already set up
password_not_configured	400	Password not yet configured
totp_already_configured	409	TOTP already enabled
totp_not_configured	400	TOTP not enabled
rate_limit_exceeded	429	Too many failed attempts
validation_error	400	Invalid request (e.g., password too short)

Authentication Flow

Initial Setup

Login (Password Only)

Login (Password + TOTP)

Related

• Features → Dashboard Auth - Overview and configuration
• Configuration → Environment Variables - Session encryption settings
• API Keys Management - Separate API key authentication