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 { env, oauth2, stitch } from 'stitchapi';

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.

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 { env, oauth2, stitch } from 'stitchapi';

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