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.

bearer

Attaches Authorization: Bearer <token>.

import { bearer } from 'stitchapi';

apiKey

Sends a secret in a header (x-api-key by default), or — with in: 'query' — as a URL query parameter (api_key by default), resolved and URL-encoded at call time.

import { apiKey } from 'stitchapi';

basic

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

import { basic } from 'stitchapi';

cookieSession

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.

oauth2

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

env

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 optionalEnv.

import { env } from 'stitchapi';

optionalEnv

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(optionalEnv('GITHUB_TOKEN'))); a missing variable just sends the request unauthenticated. See the Bearer guide.

import { optionalEnv } from 'stitchapi';

secretsFile

Resolves a secret from ~/.stitch/secrets.json (plaintext JSON — keep it private), falling back to the environment.

import { secretsFile } from 'stitchapi';

secretFrom

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, secretFrom } from 'stitchapi';

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

const auth = bearer(secretFrom(configService, 'GITHUB_TOKEN'));

See also