Principle:Langchain ai Langgraph Server Authentication
| Attribute | Value |
|---|---|
| Knowledge Sources | LangGraph |
| Domains | Authentication, Security |
| Last Updated | 2026-02-11 15:00 GMT |
Overview
Server authentication is the principle by which LangGraph Server verifies the identity of incoming requests and enforces fine-grained, resource-level authorization through a decorator-based handler framework.
Description
LangGraph Server authentication operates in two phases: authentication (who is the caller?) and authorization (what are they allowed to do?).
Authentication is handled by a single async function registered via the @auth.authenticate decorator. This handler receives request-level parameters by name injection, including the Authorization header, request path, HTTP method, raw headers, path parameters, and query parameters. It verifies credentials (typically a JWT bearer token) and returns a user representation -- either a simple string identity, a MinimalUserDict TypedDict, or an object conforming to the BaseUser protocol (which includes identity, is_authenticated, display_name, and permissions properties).
If authentication fails, the handler raises an HTTPException. This exception defaults to a 401 "Unauthorized" status code and supports custom detail messages and additional response headers (e.g., WWW-Authenticate: Bearer). The detail message is automatically derived from the HTTP status phrase when not explicitly provided.
Authorization is handled through a hierarchical decorator API on the Auth.on namespace. Handlers can be registered at three levels of specificity:
- Global (
@auth.on) -- catch-all fallback for any resource and action. - Resource-level (
@auth.on.threads,@auth.on.assistants,@auth.on.crons,@auth.on.store) -- applies to all actions on a given resource. - Action-level (
@auth.on.threads.create,@auth.on.threads.read, etc.) -- applies to a specific action on a specific resource.
The most specific matching handler wins: action-specific overrides resource-level, which overrides global. Each handler receives an AuthContext (with user info, resource, and action) and a mutable request payload typed per endpoint. Handlers return None/True to allow, False to deny with 403, or a FilterType dict to apply metadata-based filters on read operations.
The type system provides typed operation payloads per resource and action (ThreadsCreate, RunsCreate, StoreGet, StorePut, etc.), and a StudioUser class for requests originating from the LangGraph Studio UI.
Usage
Use server authentication when deploying LangGraph Server with custom security requirements. Create an auth.py file, instantiate Auth(), register your authenticate and authorize handlers, and reference the file in langgraph.json under "auth": {"path": "./auth.py:my_auth"}. This is essential for multi-tenant deployments where different users must be isolated from each other's threads, runs, and stored data.
Theoretical Basis
The authentication model implements the chain of responsibility pattern, where a single authentication handler verifies identity and multiple authorization handlers form a specificity-based chain. The most specific handler for a given resource-action pair takes precedence, allowing broad default policies to coexist with targeted overrides.
The separation of authentication from authorization follows the principle of least privilege: authentication establishes identity, while authorization restricts access to the minimum required scope. The FilterType return value enables attribute-based access control (ABAC), where read operations are automatically filtered by metadata attributes (such as ownership) rather than relying on the application to enforce access rules manually.
The hierarchical decorator API implements a specificity cascade similar to CSS selector precedence: global rules provide defaults, resource rules narrow scope, and action rules provide precise control. This reduces boilerplate by letting developers define only the rules that differ from the default, while ensuring every request is covered.
The HTTPException class provides a standardized error signaling mechanism that integrates with HTTP semantics, defaulting to 401 for authentication failures and supporting 403 for authorization denials.