JWT Authentication in Dify#

Overview#

Dify uses JWT (HS256) for authenticating both console (admin/developer) and web app (end-user) API requests. All tokens are signed and verified by PassportService using dify_config.SECRET_KEY. The console flow additionally issues a refresh token (non-JWT, Redis-backed) and a CSRF token (JWT). Web app tokens (public-site passports) have no expiry by default.

Core Signing Primitive: PassportService#

api/libs/passport.py is the single signing/verification entry point:

• issue(payload) — encodes a dict as a signed HS256 JWT 1
• verify(token) — decodes and validates; raises Unauthorized on expiry, bad signature, or decode errors 2
• SECRET_KEY must be identical across all API processes (workers, WebSocket servers, Kubernetes pods). A mismatch produces InvalidSignatureError and silently rejects all tokens.

Console Login Flow#

Entry point: POST /console/api/login in api/controllers/console/auth/login.py.

1. Credentials are validated; AccountService.login() is called.
2. AccountService.get_account_jwt_token() builds the access token payload: {user_id, exp, iss: EDITION, sub: "Console API Passport"}. Expiry = ACCESS_TOKEN_EXPIRE_MINUTES (default 60 min) 3.
3. A 128-char random hex refresh token is stored in Redis with a TTL of REFRESH_TOKEN_EXPIRE_DAYS (default 30 days) 4.
4. A CSRF token (short-lived JWT with {exp, sub: user_id}) is also issued.
5. All three are returned as HTTP-only, SameSite=Lax cookies — not in the response body.

Token refresh: POST /console/api/refresh-token looks up the refresh token in Redis, returns a new access + refresh + CSRF pair, and invalidates the old refresh token.

Console Request Verification#

Flask-Login's load_user_from_request hook in api/extensions/ext_login.py intercepts every request to the console blueprint:

1. extract_access_token() checks the COOKIE_NAME_ACCESS_TOKEN cookie first, then the Authorization: Bearer <token> header.
2. PassportService().verify(token) is called; user_id is extracted from the payload.
3. Console tokens must not have a token_source field (that field is reserved for webapp login tokens and its presence causes a 401).

Web App (End-User) Passport Flow#

Entry point: GET /api/passport in api/controllers/web/passport.py.

Public apps (no enterprise auth)#

The endpoint creates or reuses an anonymous EndUser and issues a no-expiry JWT 5:

payload = {iss: app_id, sub: "Web API Passport", app_id, app_code, end_user_id}

No exp field — tokens are permanent session identifiers tied to the site.

Enterprise-authenticated apps (INTERNAL / EXTERNAL)#

1. A webapp_login_token is obtained via WebAppAuthService.login() after email/password authentication.
2. This login token's payload includes token_source: "webapp_login_token" and expiry = ACCESS_TOKEN_EXPIRE_MINUTES (default 60 min) 6.
3. The /passport endpoint exchanges this login token for a scoped webapp access token 7, re-using the original exp if present 8.
4. The issued webapp token carries: {iss: site.id, sub: "Web API Passport", app_id, app_code, user_id, end_user_id, auth_type, token_source: "webapp", exp}.

decode_enterprise_webapp_user_id() at the /passport endpoint validates that the presented token has token_source == "webapp_login_token" before exchange 9.

Token Expiry Summary#

Key Files#