Implementation:Langchain ai Langgraph Auth Types

Knowledge Sources	Langchain_ai_Langgraph
Domains	Authentication, Types
Last Updated	2026-02-11 16:00 GMT

Overview

The auth types module defines the full set of protocols, dataclasses, TypedDicts, and type aliases used by the LangGraph Server authentication and authorization system.

Description

`types.py` provides the type-level contract for the entire auth subsystem. It defines three layers of types: user representations, authentication context, and resource-specific operation payloads.

User types include `MinimalUser` (a runtime-checkable protocol requiring only an `identity` property), `BaseUser` (extending with `is_authenticated`, `display_name`, and `permissions`), `MinimalUserDict` (a TypedDict alternative), and `StudioUser` (a concrete class for requests originating from the LangGraph Studio UI). The `Authenticator` type alias captures the allowed return types from authentication handlers.

Authentication context is modeled by `BaseAuthContext` (holding the authenticated `user` and `permissions`) and `AuthContext` (extending with the `resource` and `action` being accessed). `AuthContext` is marked `@typing.final` and uses `dataclass(slots=True)` for performance. The `resource` field is a literal union of `"runs"`, `"threads"`, `"crons"`, `"assistants"`, and `"store"`, while `action` covers CRUD operations plus store-specific actions like `"put"`, `"get"`, and `"list_namespaces"`.

Operation payloads are TypedDicts organized by resource: `ThreadsCreate`, `ThreadsRead`, `ThreadsUpdate`, `ThreadsDelete`, `ThreadsSearch` for threads; `RunsCreate` for runs; `AssistantsCreate/Read/Update/Delete/Search` for assistants; `CronsCreate/Read/Update/Delete/Search` for crons; and `StoreGet/Search/Put/Delete/ListNamespaces` for the key-value store. Each TypedDict uses `total=False` to make all fields optional, matching the flexible nature of API payloads. The module also defines supporting type aliases like `RunStatus`, `MultitaskStrategy`, `OnConflictBehavior`, `IfNotExists`, `ThreadStatus`, `FilterType`, `HandlerResult`, and `Handler`.

The `on` namespace class provides a pure-type mirror of the `Auth.on` decorator hierarchy, with nested classes for each resource and action. Each leaf class has a `value` attribute pointing to the corresponding TypedDict, enabling `Auth.on.threads.create.value` as a type annotation in handler signatures.

Usage

Import these types to annotate your authentication and authorization handler functions. The `AuthContext` type is used as the `ctx` parameter, while the `on` namespace provides `value` types for the `value` parameter. User types like `MinimalUserDict` are used as return type annotations for `@auth.authenticate` handlers.

Code Reference

Source Location

• Repository: Langchain_ai_Langgraph
• File: libs/sdk-py/langgraph_sdk/auth/types.py

Signature

# User Protocols
class MinimalUser(Protocol):
    @property
    def identity(self) -> str: ...

class BaseUser(Protocol):
    @property
    def is_authenticated(self) -> bool: ...
    @property
    def display_name(self) -> str: ...
    @property
    def identity(self) -> str: ...
    @property
    def permissions(self) -> Sequence[str]: ...

class MinimalUserDict(TypedDict, total=False):
    identity: Required[str]
    display_name: str
    is_authenticated: bool
    permissions: Sequence[str]

class StudioUser:
    def __init__(self, username: str, is_authenticated: bool = False) -> None: ...

# Auth Context
@dataclass(slots=True)
class BaseAuthContext:
    permissions: Sequence[str]
    user: BaseUser

@final
@dataclass(slots=True)
class AuthContext(BaseAuthContext):
    resource: Literal["runs", "threads", "crons", "assistants", "store"]
    action: Literal["create", "read", "update", "delete", "search",
                     "create_run", "put", "get", "list_namespaces"]

# Resource Operation TypedDicts (selected)
class ThreadsCreate(TypedDict, total=False): ...
class ThreadsRead(TypedDict, total=False): ...
class RunsCreate(TypedDict, total=False): ...
class AssistantsCreate(TypedDict, total=False): ...
class CronsCreate(TypedDict, total=False): ...
class StoreGet(TypedDict): ...
class StorePut(TypedDict): ...
class StoreSearch(TypedDict): ...

# Type namespace
class on:
    value = dict[str, Any]
    class threads:
        value = ThreadsCreate | ThreadsRead | ThreadsUpdate | ThreadsDelete | ThreadsSearch
        class create:
            value = ThreadsCreate
        class create_run:
            value = RunsCreate
        # ... read, update, delete, search
    class assistants: ...
    class crons: ...
    class store: ...

Import

from langgraph_sdk.auth.types import (
    AuthContext,
    BaseAuthContext,
    MinimalUser,
    BaseUser,
    MinimalUserDict,
    StudioUser,
    ThreadsCreate,
    ThreadsRead,
    RunsCreate,
    AssistantsCreate,
    StoreGet,
    StorePut,
    on,
    FilterType,
    HandlerResult,
    Handler,
    Authenticator,
)

I/O Contract

User Protocols

Type	Required Properties	Description
`MinimalUser`	`identity: str`	Minimum user representation; runtime-checkable
`BaseUser`	`identity`, `is_authenticated`, `display_name`, `permissions`	Full user protocol with dict-like access
`MinimalUserDict`	`identity: str` (required), `display_name`, `is_authenticated`, `permissions` (optional)	Dict-based user representation
`StudioUser`	All `BaseUser` properties	Concrete class for LangGraph Studio requests

AuthContext Fields

Field	Type	Description
user	`BaseUser`	The authenticated user object
permissions	`Sequence[str]`	Permissions extracted from the user
resource	`Literal["runs", "threads", "crons", "assistants", "store"]`	The API resource being accessed
action	`Literal["create", "read", "update", "delete", "search", "create_run", "put", "get", "list_namespaces"]`	The operation being performed

Thread Operation Payloads

TypedDict	Key Fields	Description
`ThreadsCreate`	`thread_id`, `metadata`, `if_exists`, `ttl`	Create a new thread
`ThreadsRead`	`thread_id`, `run_id`	Read thread or run state
`ThreadsUpdate`	`thread_id`, `metadata`, `action`	Update thread or cancel run
`ThreadsDelete`	`thread_id`, `run_id`	Delete thread or run
`ThreadsSearch`	`metadata`, `values`, `status`, `limit`, `offset`	Search threads
`RunsCreate`	`assistant_id`, `thread_id`, `run_id`, `metadata`, `multitask_strategy`	Create a run

Store Operation Payloads

TypedDict	Key Fields	Description
`StoreGet`	`namespace`, `key`	Retrieve an item by namespace and key
`StorePut`	`namespace`, `key`, `value`, `index`	Store or update an item
`StoreSearch`	`namespace`, `filter`, `limit`, `offset`, `query`	Search items in a namespace
`StoreDelete`	`namespace`, `key`	Delete an item
`StoreListNamespaces`	`namespace`, `suffix`, `max_depth`, `limit`, `offset`	List namespaces with filtering

Usage Examples

from langgraph_sdk import Auth
from langgraph_sdk.auth.types import AuthContext, on, StudioUser

auth = Auth()

@auth.authenticate
async def authenticate(authorization: str) -> Auth.types.MinimalUserDict:
    payload = decode_jwt(authorization.split(" ")[1])
    return {
        "identity": payload["sub"],
        "permissions": payload.get("scopes", []),
    }

@auth.on.threads.create
async def on_thread_create(
    ctx: AuthContext,
    value: on.threads.create.value,  # type is ThreadsCreate
) -> None:
    # Inject owner into metadata
    value.setdefault("metadata", {})["owner"] = ctx.user.identity

@auth.on.threads.search
async def on_thread_search(
    ctx: AuthContext,
    value: on.threads.search.value,  # type is ThreadsSearch
) -> Auth.types.FilterType:
    # Only return threads owned by the user
    return {"metadata": {"owner": ctx.user.identity}}

@auth.on
async def fallback(ctx: AuthContext, value: on.value) -> bool:
    # Allow Studio users, deny everyone else
    if isinstance(ctx.user, StudioUser):
        return True
    return False

Related Pages

• Principle:Langchain_ai_Langgraph_Server_Authentication