# 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 natu...

- Repository: [Haohao/lmforge-end-to-end-llmops-platform-for-multi-model-agents](https://github.com/haohao-end/lmforge-end-to-end-llmops-platform-for-multi-model-agents)
- Tags: 
- Published: 2026-03-03

---

**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`](https://github.com/haohao-end/lmforge-end-to-end-llmops-platform-for-multi-model-agents/blob/main/api/internal/service/jwt_service.py), the `JwtService.generate_token` method signs this payload using the `JWT_SECRET_KEY` environment variable.

```python

# 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`](https://github.com/haohao-end/lmforge-end-to-end-llmops-platform-for-multi-model-agents/blob/main/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.

```python

# 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)

```

```python

# 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`](https://github.com/haohao-end/lmforge-end-to-end-llmops-platform-for-multi-model-agents/blob/main/api/internal/handler/auth_handler.py) invokes Flask-Login's `logout_user()` function.

```python

# 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`](https://github.com/haohao-end/lmforge-end-to-end-llmops-platform-for-multi-model-agents/blob/main/api/internal/service/jwt_service.py) and [`api/internal/middleware/middleware.py`](https://github.com/haohao-end/lmforge-end-to-end-llmops-platform-for-multi-model-agents/blob/main/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`](https://github.com/haohao-end/lmforge-end-to-end-llmops-platform-for-multi-model-agents/blob/main/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`](https://github.com/haohao-end/lmforge-end-to-end-llmops-platform-for-multi-model-agents/blob/main/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`](https://github.com/haohao-end/lmforge-end-to-end-llmops-platform-for-multi-model-agents/blob/main/api/internal/handler/auth_handler.py). For **API** authentication, the system uses stateless JWTs validated by custom middleware in [`api/internal/middleware/middleware.py`](https://github.com/haohao-end/lmforge-end-to-end-llmops-platform-for-multi-model-agents/blob/main/api/internal/middleware/middleware.py), creating per-request sessions without server-side state storage.