Guides & concepts

Headers and auth

Static values, async providers, and the cache trap.

Headers can be a plain record or a function. Functions are resolved per request, which is what makes them suitable for tokens that expire.

createApi({
  baseUrl,
  headers: [
    { 'X-Client': 'web' },
    async ({ signal }) => ({ Authorization: `Bearer ${await token(signal)}` }),
  ],
  services: { users },
});

Providers receive the request’s abort signal, so a token refresh can abandon its work when the request that asked for it has already been cancelled. The parameter is optional, so existing zero-argument providers still type-check.

Precedence

Headers merge API → service → endpoint, and the last writer of a given name wins. withHeaders on a chain appends after all of them.