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

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)

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
401	INVALID_OTP	Wrong OTP code
403	USER_SUSPENDED	Account is suspended

Example

curl -X POST http://localhost:8055/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.

---

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.