Dashboard Authentication

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

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"}'

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

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

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

Overview

OpenAI-Compatible Endpoints

Codex Endpoints

Management API

​Overview

​GET /api/dashboard-auth/session

​Response

​Example Request

​Example Response

​POST /api/dashboard-auth/password/setup

​Request Body

​Response

​Example Request

​POST /api/dashboard-auth/password/login

​Request Body

​Response

​Rate Limiting

​Example Request

​POST /api/dashboard-auth/password/change

​Request Body

​Example Request

​DELETE /api/dashboard-auth/password

​Request Body

​Example Request

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

​Response

​Example Request

​Example Response

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

​Request Body

​Example Request

​POST /api/dashboard-auth/totp/verify

​Request Body

​Response

​Rate Limiting

​Example Request

​POST /api/dashboard-auth/totp/disable

​Example Request

​POST /api/dashboard-auth/logout

​Example Request

​Session Management

​Session Cookie

​Session State

​Error Codes

​Authentication Flow

​Initial Setup

​Login (Password Only)

​Login (Password + TOTP)

​Related

Build docs developers (and LLMs) love

Overview

GET /api/dashboard-auth/session

Response

Example Request

Example Response

POST /api/dashboard-auth/password/setup

Request Body

Response

Example Request

POST /api/dashboard-auth/password/login

Request Body

Response

Rate Limiting

Example Request

POST /api/dashboard-auth/password/change

Request Body

Example Request

DELETE /api/dashboard-auth/password

Request Body

Example Request

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

Response

Example Request

Example Response

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

Request Body

Example Request

POST /api/dashboard-auth/totp/verify

Request Body

Response

Rate Limiting

Example Request

POST /api/dashboard-auth/totp/disable

Example Request

POST /api/dashboard-auth/logout

Example Request

Session Management

Session Cookie

Session State

Error Codes

Authentication Flow

Initial Setup

Login (Password Only)

Login (Password + TOTP)

Related