Authentication

RAG-DocBot uses JWT (JSON Web Token) based authentication with short-lived access tokens and longer-lived refresh tokens.

---

Token Lifetimes

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

---

Public Endpoints

The following endpoints do not require authentication:

• GET /api/health
• GET /api/branding
• GET /api/branding/logo

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

---

Auth Endpoints

Endpoint	Description
POST /api/auth/login	Exchange username + password for access and refresh tokens
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)

---

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	Access token lifetime in seconds
REFRESH_TOKEN_EXPIRE_SECONDS	604800	Refresh token lifetime in seconds
DEFAULT_ADMIN_USER	admin	Username for the default admin account
DEFAULT_ADMIN_PASSWORD	changeme	Password for the default admin account

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.

---

Example: Login and Call a Protected Endpoint

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:

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

2. Call a protected endpoint

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

3. Refresh the access token

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

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