Login / Logout / Refresh Endpoints

All auth endpoints are under /auth/. No authentication required unless noted.

POST /auth/login

Authenticate with email and password.

Request Body

{
  "email": "admin@example.com",
  "password": "secret",
  "provider": "default",
  "otp": "123456",
  "mode": "session"
}

Field	Required	Description
email	Yes	User email address
password	Yes	User password
provider	No	Auth provider name (default: "default")
otp	No	TOTP code (required if TFA is enabled)
mode	No	Set to "session" to receive refresh token as HttpOnly cookie

Response 200

{
  "data": {
    "access_token": "eyJhbGciOiJIUzI1NiJ9...",
    "expires": 900000,
    "refresh_token": "a1b2c3d4...",
    "post_login_action": "none",
    "password_expired_at": "2025-01-01T00:00:00.000Z"
  }
}

Field	Description
access_token	Short-lived JWT (default TTL: 15 minutes)
expires	Access token TTL in milliseconds
refresh_token	Long-lived token for refreshing (default TTL: 7 days). Absent when mode=session (sent as cookie instead)
post_login_action	Pending action the client must resolve before the session is fully usable: none, or one of must_change_password / password_expired / tfa_setup_required (#44/#45/#46). Always present
password_expired_at	Optional — the timestamp at which the current password expires, when a password-age policy is configured

Session Cookie Mode

When mode=session and SESSION_COOKIE_ENABLED=true, the refresh_token is set as an HttpOnly, Secure, SameSite=Lax cookie named odp_session_token. The response body still contains access_token and expires.

Errors

Status	Code	Description
400	INVALID_PAYLOAD	Missing email or password
401	INVALID_CREDENTIALS	Wrong email or password (also returned for a wrong OTP code)
401	OTP_REQUIRED	Account has TFA enabled (tfa_secret set) but no otp was supplied
403	FORBIDDEN	Email/password login is disabled — the local driver is used while an admin has turned off password login (#30)
403	USER_SUSPENDED	Account is suspended

Example

curl -X POST http://localhost:6688/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"admin@example.com","password":"secret"}'

---

POST /auth/refresh

Exchange a refresh token for a new access token.

Request Body

{
  "refresh_token": "a1b2c3d4...",
  "mode": "session"
}

Field	Required	Description
refresh_token	Yes*	Refresh token. Not needed when using cookie mode (read from cookie automatically)
mode	No	"session" to set new refresh token as cookie

Response 200

{
  "data": {
    "access_token": "eyJhbGciOiJIUzI1NiJ9...",
    "expires": 900000,
    "refresh_token": "e5f6g7h8..."
  }
}

The old refresh token is invalidated. Each refresh issues a new refresh token (token rotation).

Errors

Status	Code	Description
400	INVALID_PAYLOAD	Missing refresh_token
401	INVALID_TOKEN	Token expired or not found

---

POST /auth/logout

Invalidate a refresh token (and its associated session).

Request Body

{
  "refresh_token": "a1b2c3d4..."
}

When using cookie mode, the cookie is read automatically.

Response 204 (no body)

Also clears the session cookie if SESSION_COOKIE_ENABLED=true.

---

GET /auth/config

Public login configuration for the login screen (#30). Lets the client hide the password form and auto-redirect when exactly one SSO provider is configured.

Auth required: No (public)

Response 200

{
  "data": {
    "password_login_enabled": true,
    "sso_providers": []
  }
}

Field	Description
password_login_enabled	false when an admin has disabled email/password login
sso_providers	Public info for the configured SSO providers

---

POST /auth/password/request

Request a password reset email.

Request Body

{
  "email": "user@example.com",
  "reset_url": "https://app.example.com/reset"
}

Field	Required	Description
email	Yes	The user's email address
reset_url	No	Custom reset URL for the email link

Response 204 — Always returns 204, even if email does not exist (prevents enumeration).

---

POST /auth/password/reset

Reset password using the token from the email.

Request Body

{
  "token": "reset-token-from-email",
  "password": "new-password"
}

Response 204

---

Related Auth Pages

• SSO & SAML Authentication — Full documentation of OAuth2, OpenID, and SAML SSO flows, provider configuration, and the verify/ACS endpoints.
• Impersonation System — Start/stop impersonation sessions, access controls, JWT structure, and audit trail.
• Sub-Tokens (API Keys) — Create scoped, long-lived API tokens with role restrictions and expiry.