Introduction to auth, and authentication

Multi-tenant auth is where this domain stops being about shipping and starts being about not leaking. It is also unusually clean conceptually, which is good news: the split here is sharper than in most systems you have worked in.

The sentence to hold

Authentication verifies identity through the @auth.authenticate handler. Authorization determines access permissions via the @auth.on handlers.

Learn it with the handler names attached, because a question that gives you a handler and asks what it does is the same question as one that gives you a job and asks which handler. Two words that sound alike, get abbreviated to authn and authz precisely because they sound alike, and then get tested against each other.

Where the policy lives

The handler module is wired in through the auth key in langgraph.json, and the shape of that key is worth noticing:

{ "auth": { "path": "./src/auth.ts:auth" } }

That is a module path, exactly like the graphs key. Your auth policy is code the server loads and calls, not a declarative rule set the platform evaluates. That design choice is why arbitrary policy is expressible at all, and it is why the next lesson is about return values rather than about a permissions matrix.

Authenticate: one question, once

@auth.authenticate answers who is this.

A request arrives with a token, a header, whatever your scheme uses. This handler turns that into an identity, and whatever it establishes is what every downstream decision reasons about. One question, one answer, once per request.

Authorize: many questions, fanned out

@auth.on answers what may they touch, and that is not one question. May they read this thread? Create a run? Write to the store? Delete a cron? Each is a separate decision about the same identity.

The confusion that generates distractors

Here is the move the exam makes, and it is fair, because it happens in real code constantly.

Tokens carry claims. Claims often look like permissions: a role, a workspace id, a tenant. So it feels natural to say “the token already knows they are an admin, so the authenticating handler should reject non-admins.”

Reading a claim is not making an access decision. authenticate extracts the identity and whatever travels with it. on decides whether that identity may do this specific thing to this specific resource. Same information, different job, different handler. Hold that line and you will not be caught by an option that puts an access check inside the authenticating handler, and that option will absolutely be on the page.

The same thing in TypeScript

These are written as Python decorators, and a decorator is a Python language feature, so the TypeScript surface cannot look like @auth.on. It does not. What it does instead is a chained builder on an Auth class, and the mapping is one to one:

import { Auth, HTTPException } from "@langchain/langgraph-sdk/auth";

export const auth = new Auth()
  .authenticate(async (request: Request) => {
    const token = request.headers.get("authorization");
    const user = await validateWithYourProvider(token);
    if (!user) throw new HTTPException(401, { message: "Invalid token" });
    return { identity: user.id, permissions: user.scopes };
  })
  .on("threads", ({ user }) => {
    return { owner: user.identity };
  });

That file is what the auth.path key points at, which is why the config example above reads "./src/auth.ts:auth".

Four things to read off it:

• .authenticate() takes a plain web Request. Not a framework-specific request object; the standard one. So header reading is request.headers.get(...).

• The returned identity uses snake_case fields even in TypeScript: identity is the only required one, alongside permissions, display_name and is_authenticated. is_authenticated defaults to true and display_name defaults to the identity, so a minimal return is genuinely just { identity }. You may also return a bare string, which is treated as the identity. This is the detail most likely to catch a TypeScript developer out, because every instinct says isAuthenticated.

  Note which way that default leans. Returning at all is what authenticates the caller, so a handler that returns an identity on a path where verification did not actually succeed has authenticated them. is_authenticated: false is something you opt into, not a state you fall back to. The next lesson’s rule follows from this: when validation cannot complete, throw rather than return.

• .on() takes the event as a string argument rather than as a decorator target, and that string is where the specificity ladder lives: "*", a resource like "threads", an action like "*:create", or a specific event like "threads:create". Same ladder, expressed as an argument instead of as a decorator name.

• Rejection is a thrown HTTPException, which is exported from the same module.

There is one more export worth knowing by name: isStudioUser(), which tells you whether a request came from LangGraph Studio. Custom authorization applies to Studio traffic too by default, so without it your own policy can lock you out of your own Studio.