Auth strategies

The signatures for every auth strategy and secret resolver. Each strategy holds the credential and resolves it at call time, so the caller never sees it. The guides under Auth show how to use them.

bearerCopy Anchor Link

Attaches Authorization: Bearer <token>.

import { bearer } from 'stitchapi/auth';

apiKeyCopy Anchor Link

Sends a secret in a header (X-API-Key by default), a query parameter (in: 'query', api_key by default, URL-encoded), or a cookie (in: 'cookie'). name labels the key in every arm, resolved at call time.

import { apiKey } from 'stitchapi/auth';

basicCopy Anchor Link

Base64-encodes user:pass into Authorization: Basic ….

import { basic } from 'stitchapi/auth';

cookieSessionCopy Anchor Link

Logs in once, captures the cookie from Set-Cookie, replays it on each request, and re-logs in on a status code or a soft 200 wall.

oauth2Copy Anchor Link

Performs the client_credentials grant, caches the access token, refreshes it before expiry, and attaches it as Authorization: Bearer ….

OAuth2ClientOptionsCopy Anchor Link

The shape behind oauth2({ client }) — who the client is at the token endpoint, and how it proves it. id and secret are both required, so client: {} is a compile error; there is no scalar shorthand, because neither field dominates the other. auth picks client_secret_post (the default) or client_secret_basic.

envCopy Anchor Link

The environment-variable resolver, and the only one whose source is the process environment. It is callable for the required case, with the optional variant hanging off it as a modifier — one name for one source, requiredness named at the call site.

Resolves a required secret from an environment variable at call time. It needs a non-empty value: an unset variable and a set-but-empty one (MY_TOKEN=) both throw, so a blank credential is never silently sent. For the may-or-may-not-be-set case use env.optional.

import { env } from 'stitchapi/auth';

env.optionalCopy Anchor Link

Like env, but optional: resolves the variable's value, or absent when it is unset or empty — it never throws. Pass it to bearer to attach the credential only when present (bearer(env.optional('GITHUB_TOKEN'))); a missing variable just sends the request unauthenticated. See the Bearer guide.

import { env } from 'stitchapi/auth';

const token = env.optional('GITHUB_TOKEN');

credentialCopy Anchor Link

The resolvers whose source is not the process environment, grouped under one noun with the source named at the call site. Both members are required resolvers — they throw rather than hand back a blank credential, mirroring env — and both return the same () => string thunk every strategy accepts.

The noun is credential rather than secrets because secrets is already the root barrel's trace-redaction namespace (secrets.register / has / redact); two different objects behind one word on two entry points is the one-word-one-concept rule this project holds itself to.

credential.fileCopy Anchor Link

Resolves a secret from ~/.stitch/secrets.json (plaintext JSON — keep it private), falling back to the environment variable of the same name when the file is absent or lacks the key, and throwing when neither has it.

import { credential } from 'stitchapi/auth';

const token = credential.file('BILLING_TOKEN');

credential.fromCopy Anchor Link

Resolves a required secret from an arbitrary injected source at call time — for DI'd apps that supply config without touching process.env (a ConfigService, a secrets-manager client, a validated config object). The source is either an object with a get(name) method or a plain (name) => value function; a missing or empty value throws, mirroring env. Compose it with any strategy exactly like env().

import { bearer, credential } from 'stitchapi/auth';

// Any object with a `get(name)` method — e.g. a NestJS ConfigService.
declare const configService: { get(name: string): string | undefined };

const auth = bearer(credential.from(configService, 'GITHUB_TOKEN'));

See alsoCopy Anchor Link