How LMForge Implements JWT Token Refresh, Revocation, and Session Management

LMForge uses a hybrid authentication architecture that combines stateless JWTs with 30-day expiration for API access and Flask-Login session cookies for web UI interactions, explicitly omitting refresh tokens in favor of natural expiration-based revocation.

The haohao-end/lmforge-end-to-end-llmops-platform-for-multi-model-agents repository implements a dual-mode authentication system designed to support both programmatic API access and browser-based user interactions. Understanding how LMForge handles JWT token lifecycle management, revocation strategies, and session state is critical for developers integrating with the platform or extending its authentication mechanisms.

JWT Token Generation and Expiration Strategy

LMForge generates JSON Web Tokens upon successful authentication via password or OAuth flows. The system encodes specific claims into the JWT payload to enforce security boundaries and automatic expiration.

Token Payload Structure and Signing

When a user authenticates, the system constructs a payload containing the subject identifier, issuer claim, and expiration timestamp. In api/internal/service/jwt_service.py, the JwtService.generate_token method signs this payload using the JWT_SECRET_KEY environment variable.

# api/internal/service/jwt_service.py

payload = {
    "sub": str(account.id),
    "iss": "llmops",
    "exp": expire_at,
}
access_token = self.jwt_service.generate_token(payload)

The resulting token includes the exp claim set to a Unix timestamp 30 days in the future by default. This hard expiration ensures that compromised tokens automatically become invalid after the configured period without requiring server-side intervention.

Absence of Refresh Tokens

Unlike OAuth 2.0 implementations that issue short-lived access tokens paired with long-lived refresh tokens, LMForge issues only a single JWT per authentication event. When the token expires, clients must re-authenticate using valid credentials to obtain a new token. This design simplifies the architecture by eliminating refresh token rotation logic and storage requirements.

API Authentication and Request-Level Session Management

LMForge validates JWTs at the middleware layer for all routes registered under the llmops blueprint. This validation creates an ephemeral, per-request session context that binds the authenticated user to the current request lifecycle.

Middleware Token Validation

The custom middleware in api/internal/middleware/middleware.py intercepts incoming requests to extract and validate the Authorization header. The JwtService.parse_token method decodes the JWT using the HS256 algorithm and secret key, raising UnauthorizedException for expired or malformed tokens.

# api/internal/middleware/middleware.py

payload = self.jwt_service.parse_token(access_token)
account_id = payload.get("sub")
return self.account_service.get_account(account_id)

# api/internal/service/jwt_service.py

return jwt.decode(token, secret_key, algorithms=['HS256'])

# raises UnauthorizedException on ExpiredSignatureError / InvalidTokenError

Per-Request Session Handling

Upon successful validation, the middleware retrieves the corresponding Account model instance and attaches it to the request context. This creates a stateless, per-request session that exists only for the duration of the HTTP request processing. The system does not maintain server-side session storage for API clients, adhering to RESTful statelessness principles while ensuring secure identity verification for each transaction.

Token Revocation and Logout Mechanisms

LMForge implements a stateless revocation strategy that relies on token expiration rather than maintaining a revocation list. This approach eliminates the need for persistent storage of invalidated tokens but imposes specific constraints on session termination.

Stateless Revocation via Natural Expiration

The primary revocation mechanism is the exp claim embedded in the JWT. Because the system does not maintain a token blacklist or revocation table in the database, there is no mechanism to invalidate an active token before its natural expiration. Once issued, a JWT remains valid until the Unix timestamp specified in the exp claim is reached, regardless of user actions or administrative decisions.

Web UI Session Termination with Flask-Login

For browser-based interactions, LMForge utilizes Flask-Login to manage traditional server-side session cookies. When a user initiates logout through the web interface, the AuthHandler.logout method in api/internal/handler/auth_handler.py invokes Flask-Login's logout_user() function.

# api/internal/handler/auth_handler.py

@login_required
def logout(self):
    logout_user()                                   # clears Flask‑Login session cookie

    return success_message("退出登陆成功")

This operation clears the session cookie from the client browser and removes the server-side session reference, immediately terminating the web UI session. However, this action does not affect previously issued JWTs, which remain valid for API access until expiration. To achieve complete revocation across both interfaces, developers would need to implement a JWT blacklist table and modify Middleware._validate_credential to query that table on each request.

Summary

• Hybrid Architecture: LMForge combines Flask-Login session cookies for web UI authentication with stateless JWTs for API access, defined in api/internal/service/jwt_service.py and api/internal/middleware/middleware.py.
• 30-Day Expiration: JWTs carry an exp claim set to 30 days by default, ensuring automatic token invalidation without server-side storage.
• No Refresh Tokens: The system issues single long-lived tokens; clients must re-authenticate after expiration rather than using refresh token rotation.
• Stateless Revocation: LMForge does not maintain a token blacklist; revocation relies entirely on natural expiration, with Flask-Login handling web session termination separately via logout_user() in api/internal/handler/auth_handler.py.

Frequently Asked Questions

Does LMForge support refresh tokens?

No, LMForge does not implement a refresh token mechanism. The architecture issues a single JWT with a 30-day expiration period upon authentication. When this token expires, API clients must submit valid credentials again to obtain a new access token. This design simplifies token management by eliminating the need for refresh token storage and rotation logic.

How does LMForge handle JWT revocation?

LMForge employs a stateless revocation strategy that relies on the exp claim within the JWT. The system does not maintain a revocation list or blacklist table. Once issued, a token remains valid until its expiration timestamp is reached, regardless of user logout actions. To implement immediate revocation, developers would need to add a database-backed blacklist and modify the middleware validation logic in api/internal/middleware/middleware.py.

What is the default JWT expiration time?

The default expiration time for LMForge JWTs is 30 days from the time of issuance. This duration is calculated by adding 30 days to the current Unix timestamp and storing the result in the exp claim. This long-lived token approach reduces authentication frequency for API consumers while maintaining security boundaries through automatic expiration.

How does LMForge differentiate between web UI and API authentication?

LMForge utilizes a dual-mode authentication system. For web UI interactions, the platform uses Flask-Login to manage traditional server-side session cookies, enabling immediate session termination via logout_user() in api/internal/handler/auth_handler.py. For API authentication, the system uses stateless JWTs validated by custom middleware in api/internal/middleware/middleware.py, creating per-request sessions without server-side state storage.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}