Authentication#

RAGFlow's authentication system is implemented in api/apps/__init__.py and supports four credential methods with a priority-based fallback chain. All protected routes use the @login_required decorator, which calls _load_user() on every request.

Auth Types and Constants#

Three auth-type string constants are defined at module level 1:

DEFAULT_AUTH_TYPES = (AUTH_JWT, AUTH_API). Routes that need beta-token support must pass auth_types=[AUTH_BETA] explicitly to @login_required.

Resolution Order in _load_user()#

_load_user() tries credentials in this fixed sequence 2:

1. Cache hit — if g.user is already populated and the auth type matches, return immediately.
2. No Authorization header → fall through to session cookie (only if AUTH_JWT is in the allowed set).
3. Beta token (if AUTH_BETA in allowed set) — looks up APIToken.query(beta=auth_token). Sets g.auth_type = "BETA".
4. JWT (if AUTH_JWT in allowed set) — decodes the bearer token using itsdangerous.URLSafeTimedSerializer with settings.get_secret_key(), then queries UserService by access_token. Sets g.auth_type = "JWT".
5. API key (if AUTH_API in allowed set) — looks up APIToken.query(token=auth_token) as a plain API token. Sets g.auth_type = "API".

The resolved auth type is written to g.auth_type; route handlers can inspect this if needed.

Session Cookie Fallback#

_load_user_from_session() is called only when the Authorization header is absent and AUTH_JWT is permitted. It reads _user_id from the Quart session (Redis-backed) and validates the associated access_token — rejecting empty values, values shorter than 32 chars, or values prefixed INVALID_. This path exists to support OAuth/OIDC redirect flows where the frontend may clear its stored bearer token after a 401.

Token Lifecycle#

The INVALID_ prefix is checked in both _load_user_from_session() 3 and UserService.query() to prevent revoked tokens from authenticating.

The JWT signing secret is a 64-char hex string lazily created and stored in Redis, shared across all server instances 4.

The APIToken model 5 stores both plain API keys (token field) and beta tokens (beta field), scoped by tenant_id. The composite primary key is (tenant_id, token).

Error Handling#

Failed auth raises QuartAuthUnauthorized for most routes, returning HTTP 401 6. The one exception: routes restricted to AUTH_BETA only return a JSON DATA_ERROR response instead of a 401 7, matching the external API convention.

Error codes live in common/constants.py:

• UNAUTHORIZED = 401
• AUTHENTICATION_ERROR = 109
• PERMISSION_ERROR = 108

Ownership-Based Authorization on Chat Endpoints#

Authentication (who you are) is separate from authorization (what you own). Chat and session endpoints enforce a second ownership check via _ensure_owned_chat(chat_id), which queries DialogService filtering by both tenant_id=current_user.id and id=chat_id. Any mutation route — PUT, PATCH, DELETE on /chats/<chat_id> and all /chats/<chat_id>/sessions/* routes — calls this guard before proceeding 8 9 10 11. A failed ownership check returns RetCode.AUTHENTICATION_ERROR (109), not 401.

The GET /chats/<chat_id> endpoint uses a broader check: it allows any tenant the user belongs to, not just their own — querying UserTenantService first 12.

Key Files#