apiKey

Use apiKey when an API authenticates with a static key and you want the stitch to attach it as a request header, resolved at call time so the caller never sees the secret.

Example

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

const search = stitch({
    baseUrl: 'https://api.example.com',
    path: '/search',
    auth: apiKey({ secret: env('API_KEY') }),
});

Every call to search() sets the x-api-key header to the resolved key, behind the capability boundary.

Options

value is the key itself — a literal string, or (preferred) a resolver like env('API_KEY') so the secret is read at call time and never committed.

in chooses where the key goes: 'header' (the default), 'query', or 'cookie'.

name labels the key in every arm — the header name, the query-parameter name, or the cookie name. It defaults to X-API-Key for a header and api_key for a query parameter or cookie. For a custom header, pass apiKey({ name: 'X-My-Key', secret: env('API_KEY') }). A header name goes on the wire lowercased (x-my-key) — case-insensitive per HTTP, but worth knowing if a fixture asserts the original casing. See Migration notes.

In a query parameter

Some APIs (often older REST endpoints) expect the key in the query string rather than a header. Set in: 'query'; the key is appended to the request URL at call time, URL-encoded, onto whatever query the endpoint already carries:

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

const search = stitch({
    baseUrl: 'https://api.example.com',
    path: '/search?type=full', // an existing query is preserved
    auth: apiKey({ in: 'query', name: 'api_key', secret: env('API_KEY') }),
});

Every call appends &api_key=<resolved> to the URL. name is the parameter name (default api_key).

In a cookie

Some APIs read the key from a cookie. Set in: 'cookie'; the key is appended to the Cookie header as name=<resolved> at call time, merged with any cookie the request already carries:

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

const search = stitch({
    baseUrl: 'https://api.example.com',
    path: '/search',
    auth: apiKey({ in: 'cookie', name: 'api_key', secret: env('API_KEY') }),
});

The Cookie header is on StitchAPI's trace denylist, so the key is redacted from sinks exactly like a header key — no separate scrubber registration is needed.

See Reference → Auth strategies for every field.

See also