Capability, not credential

A stitch holds its credential; what it hands the caller is a capability — a callable that, when invoked, returns data. The caller gets the ability to make the authenticated call, never the secret that authorizes it.

Why it's shaped this way

A credential is not a value you want flowing through application code. The moment a token is read into a variable, passed as an argument, or logged on the way to a request, it has more places to leak from than it should. A stitch removes those places by owning the secret end to end and exposing only the act of calling.

Secrets are resolved lazily, at call time. env('NAME') and keychain('NAME') don't read anything when you declare the stitch — they return a () => string resolver that the runtime invokes on each request, reads the value, attaches it, and discards it. So the declaration carries a reference to where the secret lives, not the secret itself: it is safe to commit, diff, and share, because there is nothing sensitive in it to commit.

import { bearer, env, stitch } from 'stitchapi';

const getMovie = stitch({
    path: 'https://api.example.com/movies/{id}',
    // env('API_TOKEN') is a resolver; the runtime reads the token per call,
    // attaches it to the request, and the caller never receives it.
    auth: bearer(env('API_TOKEN')),
});

// The caller just calls the stitch and gets data — no token in sight.
const movie = await getMovie({ params: { id: 1 } });

The stitch also owns the whole auth lifecycle, not just the one header. Each AuthStrategy — bearer, apiKey, basic, cookieSession, oauth2 — attaches the secret to the request inside the runtime; the strategies that have a session detect when they hit a wall and refresh it (re-login, fetch a new token) without the caller doing anything. Attach, detect, refresh: all of it happens behind the capability, so the caller never sees the token even when the token is rotating underneath them.

That is the security boundary that makes a stitch safe to expose to an agent. You can hand an agent a stitch and let it invoke the call without granting it the credential — the agent operates with a capability scoped to exactly that endpoint, and a leak in the agent's context can't leak a secret that was never in it.

How it relates

This boundary is the why behind the auth machinery, which the guides cover in detail. The secret resolvers env() and keychain() are the lazy lookup that keeps secrets out of the declaration; the auth strategies — bearer here, cookieSession for login-and-cookie APIs — are what attaches and refreshes the secret inside the runtime.

The boundary is what lets the agent surfaces exist: a stitch invoked through MCP or the run_stitch tool runs its auth on the runtime's side of the line, so the agent gets a structured result and never a token. And when a session can't be refreshed — an expired login, a soft 200 wall — the lifecycle surfaces a typed STITCH_AUTH_WALL error rather than silently returning a login page, so a failed capability is a loud, structured signal too.

See also