oauth2

Use oauth2 when an API authenticates with the OAuth2 client_credentials grant and you want the access token fetched, cached, and refreshed for you — the stitch holds the client id and secret, the caller never sees the token.

Example

import { stitch } from 'stitchapi';
import { env, oauth2 } from 'stitchapi/auth';

const orders = stitch({
    baseUrl: 'https://api.example.com',
    path: '/orders',
    auth: oauth2({
        tokenUrl: 'https://api.example.com/oauth/token',
        clientId: env('CLIENT_ID'),
        clientSecret: env('CLIENT_SECRET'),
        scope: 'orders.read',
    }),
});

The first call to orders() POSTs the form-encoded token request, caches the token in the stitch store (TTL from expires_in), and attaches it as Authorization: Bearer …; later calls reuse the cached token until it nears expiry, all behind the capability boundary.

Options

tokenUrl is the client_credentials token endpoint. Pass clientId and clientSecret as secret resolvers — e.g. env('CLIENT_ID') — so the credentials are read at call time and never committed. scope is an optional space-delimited scope string.

The token is cached and auto-refreshed through one refresh envelope (CONTRACT.md P24). A bare StatusMatch — a status, a list, or a predicate — is shorthand for refresh: { on }: the status(es) that mean the token was rejected and force a fresh fetch plus retry (default [401], and refresh: 419 ≡ refresh: { on: [419] }). Reach refresh.skew — how many milliseconds before expiry to refresh so the token is never used mid-flight (default 30_000) — through the envelope form: refresh: { skew: '1m' }.

Give two stitches the same key plus a shared store and one token serves them all — across stitches and across workers, surviving restarts. See Reference → Auth strategies for every field.

This strategy covers client_credentials, where the token is yours to re-fetch at will. A provider that issues single-use refresh tokens is a different problem — two workers refreshing at once can revoke the whole grant, and the obvious guards turn out to be narrower races rather than fixes. OAuth2 refresh tokens that rotate builds the strategy that holds.

Client authentication

By default the client authenticates with client_secret_post: client_id and client_secret ride in the form body. Some providers require client_secret_basic instead — the credentials as an HTTP Basic header, with only grant_type in the body. Set clientAuth: 'basic' for those:

import { stitch } from 'stitchapi';
import { env, oauth2 } from 'stitchapi/auth';

const messages = stitch({
    baseUrl: 'https://sms.example.com',
    path: '/messages',
    auth: oauth2({
        tokenUrl: 'https://sms.example.com/oauth/token',
        clientId: env('CLIENT_ID'),
        clientSecret: env('CLIENT_SECRET'),
        clientAuth: 'basic',
    }),
});

The Basic header is Base64 of id:secret, encoded without Node's Buffer so it works in a browser bundle too. For provider-specific extras on the token request, audience sets the OAuth2 audience field, params merges arbitrary fields into the token-request body (e.g. resource, or a custom grant_type), and headers adds headers to it. The client credentials are always applied last, so params can never shadow them.

See also