Authentication

RAG-DocBot uses JWT (JSON Web Token) based authentication with short-lived access tokens and longer-lived refresh tokens. Starting from v1.8.0, the system also supports TOTP MFA, federated login via OIDC/SSO, and group-based resource ACLs.

Authentication Methods

Method	Description
Username / password	Standard local account login
TOTP MFA	Optional time-based one-time password second factor (v1.8.0+)
OIDC / SSO	Federated login via OpenID Connect (v1.8.0+)

Token Lifetimes

Token	Default Lifetime
Access token	15 minutes (900 seconds)
Refresh token	7 days (604800 seconds)

Token lifetimes can be updated at runtime without a restart via PATCH /api/admin/auth/settings. Enterprise plans support per-role overrides (access_token_seconds_admin, refresh_token_seconds_admin).

Public Endpoints

The following endpoints do not require authentication:

GET /api/health
GET /api/branding
GET /api/branding/logo
GET /api/auth/oidc/providers — list available OIDC providers (v1.8.0+)

All other endpoints require a valid Bearer token in the Authorization header.

Auth Endpoints

Endpoint	Description
`POST /api/auth/login`	Exchange username + password for tokens (or `mfa_required` response if TOTP enrolled)
`POST /api/auth/totp/mfa-login`	Complete TOTP second-factor login (v1.8.0+)
`POST /api/auth/refresh`	Exchange a refresh token for a new access token
`GET /api/auth/me`	Get the currently authenticated user
`CRUD /api/auth/users`	Manage users (admin only)
`GET /api/auth/oidc/providers`	List available OIDC providers
`GET /api/auth/oidc/{provider_id}/login`	Initiate OIDC login (v1.8.0+)
`GET /api/auth/oidc/{provider_id}/callback`	OIDC callback handler (v1.8.0+)

TOTP MFA (Two-Factor Authentication)

When TOTP MFA is enabled on an account, the login flow becomes two steps:

POST /api/auth/login returns {"status": "mfa_required", "mfa_token": "..."} instead of tokens.
The client submits the 6-digit TOTP code to POST /api/auth/totp/mfa-login to receive the access and refresh tokens.

MFA tokens expire in 5 minutes and allow a maximum of 5 attempts before the token is invalidated.

For setup and management details see the MFA / TOTP guide.

OIDC providers are configured from the admin UI (stored in the oidc_providers Postgres table). Users navigating to a provider's login URL are redirected to the IdP for authentication and provisioned automatically on first login.

For setup details see the SSO / OIDC guide.

Groups & Resource ACL (Enterprise)

Starting from v1.8.0 (Enterprise tier), users can be organised into groups. Each connector and integration can restrict access to specific groups — retrieval is filtered at query time without requiring re-embedding.

For setup details see the Groups & ACL guide.

Session Revocation

Admins can revoke all active sessions at any time:

Endpoint	Description
`DELETE /api/admin/auth/sessions`	Revoke all currently-issued tokens globally
`DELETE /api/admin/auth/users/{username}/sessions`	Revoke all tokens for a single user

Both endpoints are available on all license tiers. Revocation is implemented via a watermark — tokens issued before the cut-off are rejected on the next API call.

Environment Variables

Variable	Default	Description
`JWT_SECRET_KEY`	(must be set)	Secret key used to sign JWTs — change this before deployment
`JWT_ALGORITHM`	`HS256`	Signing algorithm
`ACCESS_TOKEN_EXPIRE_SECONDS`	`900`	First-boot seed for access token lifetime (seconds). Managed at runtime via `PATCH /api/admin/auth/settings` after first boot.
`REFRESH_TOKEN_EXPIRE_SECONDS`	`604800`	First-boot seed for refresh token lifetime (seconds). Managed at runtime after first boot.
`DEFAULT_ADMIN_USER`	`admin`	Username for the default admin account
`DEFAULT_ADMIN_PASSWORD`	`changeme`	Password for the default admin account
`MFA_ENCRYPTION_KEY`	(must be set — v1.8.0+)	Fernet key used to encrypt TOTP secrets and OIDC client secrets at rest. Generate with: `python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"`. Supply via the `mfa_encryption_key` Docker secret.

warning

The default admin account is created on first startup with the credentials in .env. Change DEFAULT_ADMIN_USER, DEFAULT_ADMIN_PASSWORD, and especially JWT_SECRET_KEY before exposing the service.

warning

MFA_ENCRYPTION_KEY is required from v1.8.0 onwards. The stack will not start without it.

1. Log in and obtain tokens

curl -s -X POST http://localhost:8000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username": "admin", "password": "changeme"}'

Response (no MFA enrolled):

{
  "access_token": "<ACCESS_TOKEN>",
  "refresh_token": "<REFRESH_TOKEN>",
  "token_type": "bearer"
}

Response (TOTP enrolled — v1.8.0+):

{
  "status": "mfa_required",
  "mfa_token": "<MFA_TOKEN>"
}

2. Complete TOTP second factor (if required)

curl -s -X POST http://localhost:8000/api/auth/totp/mfa-login \
  -H "Content-Type: application/json" \
  -d '{"mfa_token": "<MFA_TOKEN>", "totp_code": "123456"}'

3. Call a protected endpoint

curl -s http://localhost:8000/api/docs \
  -H "Authorization: Bearer <ACCESS_TOKEN>"

4. Refresh the access token

curl -s -X POST http://localhost:8000/api/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{"refresh_token": "<REFRESH_TOKEN>"}'

5. Create a new user (admin only)

curl -s -X POST http://localhost:8000/api/auth/users \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"username": "alice", "password": "s3cure!", "role": "editor"}'

Authentication Methods​

Token Lifetimes​

Public Endpoints​

Auth Endpoints​

TOTP MFA (Two-Factor Authentication)​

Federated Login (OIDC / SSO)​

Groups & Resource ACL (Enterprise)​

Session Revocation​

Environment Variables​

Example: Login and Call a Protected Endpoint​

1. Log in and obtain tokens​

2. Complete TOTP second factor (if required)​

3. Call a protected endpoint​

4. Refresh the access token​

5. Create a new user (admin only)​