apiKey
Send an API key as a header or query parameter, resolved at call time.
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 { , , } from 'stitchapi';
const = ({
: 'https://api.example.com',
: '/search',
: ({ : ('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) or 'query'.
header overrides the header name (default x-api-key, lowercased) when
in: 'header': pass apiKey({ header: 'X-My-Key', value: env('API_KEY') }) to
send the key under a custom header. The 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 { , , } from 'stitchapi';
const = ({
: 'https://api.example.com',
: '/search?type=full', // an existing query is preserved
: ({ : 'query', : 'api_key', : ('API_KEY') }),
});Every call appends &api_key=<resolved> to the URL. name is the parameter name
(default api_key).
A key in the URL is exposed wherever URLs travel — server access logs,
proxies, browser history, a Referer header. Prefer in: 'header' when the
API accepts it. StitchAPI keeps the key out of its own traces two ways: the
strategy attaches it only to the request the transport sends (the start
event's URL is the pre-auth URL, so the key never lands there), and the
configured query name is registered with the URL-credential scrubber — so
if it does appear in a sink (an OTLP url.full, the structured
input.query) it is redacted to REDACTED, exactly like
api_key/access_token. None of that protects the upstream server's logs.
See Reference → Auth strategies for every field.