CopilotKit

Authentication

Pass user auth context from your frontend to the agent so it can scope tools, data, and decisions to the signed-in user.

"use client";// Auth demo — framework-native request authentication via the V2 runtime's// `onRequest` hook. The runtime route (/api/copilotkit-auth) rejects any// request whose `Authorization: Bearer <demo-token>` header is missing or// wrong.//// UX shape: the demo defaults to UNAUTHENTICATED on first paint so visitors// land on a clear sign-in card. We don't render `<CopilotKit>` until the user// has signed in at least once — that sidesteps the transport 401 that would// otherwise crash `<CopilotChat>` during its initial `/info` handshake.// After the user signs in once, `<CopilotKit>` stays mounted across the// sign-out → sign-in cycle so the post-sign-out state can actually// demonstrate the runtime rejecting unauthenticated requests in the chat// surface (the whole point of the demo).import { useEffect, useMemo, useState } from "react";import {  CopilotKit,  CopilotChat,  type CopilotKitCoreErrorCode,} from "@copilotkit/react-core/v2";import { AuthBanner } from "./auth-banner";import { SignInCard } from "./sign-in-card";import { useDemoAuth } from "./use-demo-auth";import { DEMO_TOKEN } from "./demo-token";interface AuthDemoErrorState {  message: string;  code: CopilotKitCoreErrorCode | string;}export default function AuthDemoPage() {  const {    isAuthenticated,    authorizationHeader,    hasEverSignedIn,    signIn,    signOut,  } = useDemoAuth();  const headers = useMemo<Record<string, string>>(    () => (authorizationHeader ? { Authorization: authorizationHeader } : {}),    [authorizationHeader],  );  const [authError, setAuthError] = useState<AuthDemoErrorState | null>(null);  // Clear stale errors as soon as the user re-authenticates. Without this  // the amber error surface would persist after sign-in even though the  // failure is no longer relevant.  useEffect(() => {    if (isAuthenticated) setAuthError(null);  }, [isAuthenticated]);  if (!hasEverSignedIn) {    return (      <div className="flex h-screen flex-col">        <SignInCard onSignIn={signIn} />      </div>    );  }  return (    // `useSingleEndpoint={false}` opts into the V2 multi-endpoint protocol    // (separate /info, /agents/<id>/run, etc.), which is what this demo's    // runtime route is wired up for.    <CopilotKit      runtimeUrl="/api/copilotkit-auth"      agent="auth-demo"      headers={headers}      useSingleEndpoint={false}      onError={(event) => {        setAuthError({          message: event.error?.message ?? String(event.error),          code: event.code,        });      }}    >      <div className="flex h-screen flex-col gap-3 p-6">        <AuthBanner          authenticated={isAuthenticated}          onSignOut={signOut}          onSignIn={() => signIn(DEMO_TOKEN)}        />        <header>          <h1 className="text-lg font-semibold">Authentication</h1>        </header>        {authError && !isAuthenticated && (          <div            data-testid="auth-demo-error"            className="rounded-md border border-amber-300 bg-amber-50 px-3 py-2 text-sm text-amber-900"          >            <strong className="font-semibold">              Runtime rejected the request:            </strong>{" "}            <span data-testid="auth-demo-error-message">              {authError.message}            </span>{" "}            <code className="ml-1 rounded bg-amber-100 px-1 py-0.5 font-mono text-xs">              {authError.code}            </code>          </div>        )}        <div className="flex-1 overflow-hidden rounded-md border border-neutral-200">          <CopilotChat agentId="auth-demo" className="h-full" />        </div>      </div>    </CopilotKit>  );}

You have a chat surface or a hook driving an agent and you want every agent run to know who the request came from. By the end of this guide, your frontend will forward a token, the runtime will pass it through, and your agent code will read the resulting user info on every turn.

When to use this#

  • Multi-tenant apps where the agent reads or writes per-user data.
  • Tool gating where some tools should only run for authorised users.
  • Audit and billing where every run needs an identity to attribute it to.
  • Session-aware UX where the agent's behaviour depends on the user's role or permissions.

If you don't need any of those, skip auth entirely. The agent runs anonymously and the frontend never has to care about tokens.

Frontend#

Pass your token via the properties prop. CopilotKit forwards it to LangGraph as a Bearer token automatically.

frontend/src/app/page.tsx
import { CopilotKit } from "@copilotkit/react-core/v2";

<CopilotKit
  runtimeUrl="/api/copilotkit"
  properties={{
    authorization: userToken,
  }}
>
  <YourApp />
</CopilotKit>

Backend#

LangGraph supports two deployment modes. The frontend code above is the same in both, but the backend wiring differs in where the resolved user identity lands. Pick the tab that matches where your agent runs.

On LangGraph Platform, authentication is a managed service. You declare an @auth.authenticate handler, and Platform runs it on every request before the graph starts. The handler returns a user object that becomes available to every node in the run.

backend/auth.py
from langgraph_sdk import Auth

auth = Auth()

@auth.authenticate
async def authenticate(authorization: str | None):
    if not authorization or not authorization.startswith("Bearer "):
        raise Auth.exceptions.HTTPException(status_code=401, detail="Unauthorized")

    token = authorization.replace("Bearer ", "")
    user_info = validate_your_token(token)  # your validation logic

    return {
        "identity": user_info["user_id"],
        "role": user_info.get("role"),
        "permissions": user_info.get("permissions", []),
    }

The return value of the handler shows up in every node's config["configuration"]["langgraph_auth_user"]. From there, scoping tool access or filtering data is straightforward:

backend/agent.py
async def my_agent_node(state: AgentState, config: RunnableConfig):
    user_info = config["configuration"]["langgraph_auth_user"]
    user_id = user_info["identity"]
    user_role = user_info.get("role")
    # agent logic with user context
    return state

For full handler details, see the LangGraph Platform Authentication documentation.

When you self-host the agent, there's no managed auth handler to plug into. Instead, you forward the raw token onto every run by configuring the agent dynamically — the request's properties.authorization becomes part of langgraph_config["configurable"], where every node can read it back later.

backend/demo.py
from copilotkit import CopilotKitRemoteEndpoint, LangGraphAGUIAgent

sdk = CopilotKitRemoteEndpoint(
    agents=lambda context: [
        LangGraphAGUIAgent(
            name="sample_agent",
            description="Agent with authentication support",
            graph=graph,
            langgraph_config={
                "configurable": {
                    "copilotkit_auth": context["properties"].get("authorization"),
                },
            },
        ),
    ],
)

Validation is your job in this mode. Inside any node, pull the token out of config["configurable"] and run it through your verifier. Decide the policy explicitly: reject unauthenticated calls, or fall through to an anonymous branch as the example below does.

backend/agent.py
async def my_agent_node(state: AgentState, config: RunnableConfig):
    auth_token = config["configurable"].get("copilotkit_auth")
    if auth_token:
        user_info = validate_your_token(auth_token)
        user_id = user_info["user_id"]
        user_role = user_info.get("role")
    else:
        user_id = "anonymous"
        user_role = None
    return state

Tool gating#

The most common reason to wire auth is so individual tools can decline to run. Read the resolved user inside the tool's handler and bail if the role doesn't match:

def delete_record(record_id: str, *, user: User):
    if "admin" not in user.permissions:
        raise PermissionError("admin role required")
    # do the delete

This composes with Human in the loop: gate on auth first, surface a confirmation card next, execute last.

Security checklist#

  • Always validate the token on the backend. Never trust the frontend's claim.
  • Scope every read and write to the resolved user. Auth context only matters if you actually use it to filter data.
  • Don't log raw tokens. Log the resolved user id (or anonymous) instead.
  • Use HTTPS in production. The Bearer token is sensitive.
  • Refresh strategy. Your frontend is responsible for rotating expired tokens before they reach the agent. CopilotKit doesn't refresh on your behalf.

On this page

When to use thisFrontendBackendTool gatingSecurity checklist