# API configuration

`APIConfiguration` is the object built by [`HTML.getApiConfiguration`](../../core/utils/HTML.ts) from **ancestor attributes** on the DOM (or from a typed publisher — see [@get](/docs/decorators/get) / [@post](/docs/decorators/post) configuration key). It is passed to [`API`](../../core/utils/api.ts) by fetchers, **sonic-submit**, the **`wording()`** directive, **`@get`**, **`@post`**, **`@put`**, and **`@patch`**.

> **Mock service:** same [Local API demos](/docs/misc/docs-mock-api) Service Worker / Vite middleware. Routes used on this page are listed in the [API config routes](#api-config-routes) section below.

## Attribute map

| Attribute (ancestor) | `APIConfiguration` field | Role |
|---------------------|---------------------------|------|
| `serviceURL` | `serviceURL` | Base URL (e.g. `/docs-mock-api`) |
| `token` | `token` | Static Bearer sent on REST calls |
| `userName` / `password` | `userName` / `password` | Basic auth for **tokenProvider** fetch only |
| `eventsApiToken` | `authToken` | Bearer for **tokenProvider** when no Basic |
| `tokenProvider` | `tokenProvider` | Path to GET a new token (`{ token }` JSON) |
| `wordingProvider` | — (read by `wording()`) | Base path + query for label batch GET |
| `wordingVersionProvider` | — | Publisher id; bump version → reload wordings |
| `credentials` | `credentials` | `fetch` credentials mode |
| `addHTTPResponse` | `addHTTPResponse` | Attach `_sonic_http_response_` on result |
| `cache` | `cache` | `fetch` cache mode |
| `blockUntilDone` | `blockUntilDone` | Serialize calls per `serviceURL` |
| `keepAlive` | `keepAlive` | `fetch` keepalive |

**Lit / TypeScript:** store the same shape in a publisher and pass `DataProviderKey<APIConfiguration>` as the second argument of `@get` (see [DataProviderKey](/docs/misc/dataProviderKey)).

## Bearer token (static)

Publisher `docsApiConfBearerKey` (`set(docsApiConfBearerKey, { token: "docs-mock-valid-token", … })`) — mock returns the protected payload.

<docs-lit-demo for="docs-api-config-bearer-demo"></docs-lit-demo>

## tokenProvider + Basic auth

No static `token`: `API.auth()` calls `GET /docs-mock-api/auth/token` with Basic **demo** / **secret**, stores `token`, then calls the protected route.

<docs-lit-demo for="docs-api-config-token-provider-demo"></docs-lit-demo>

## HTTP 498 — stale token refresh

Initial `token="docs-mock-stale-token"` → mock responds **498** → Concorde invalidates the token, runs `auth()` again (same `tokenProvider` + Basic), retries with `docs-mock-fresh-token`.

<docs-lit-demo for="docs-api-config-stale-token-demo"></docs-lit-demo>

## eventsApiToken

Attribute **`eventsApiToken`** on an ancestor maps to **`authToken`** in config (used as Bearer when calling `tokenProvider`, instead of Basic).

<docs-lit-demo for="docs-api-config-events-token-demo"></docs-lit-demo>

## Wording API

`wordingProvider` and `wordingVersionProvider` are read by the translation directive: see [t()](/docs/directives/t).

## Scoped attributes (HTML / sonic-scope)

Attributes on **`sonic-scope`** (or any ancestor) are visible to descendants via `getAncestorAttributeValue`.

<docs-lit-demo for="docs-api-config-scoped-attrs-demo"></docs-lit-demo>

## API config routes

| Route | Demo |
|-------|------|
| `GET /docs-mock-api/auth/token` | tokenProvider, eventsApiToken |
| `GET /docs-mock-api/api/config/protected` | Bearer / Basic / 498 |
| `GET /docs-mock-api/wording/labels?labels[]=…&lang=fr` | `wording()` |

Mock tokens (doc only): `docs-mock-valid-token`, `docs-mock-stale-token` (498), `docs-mock-fresh-token` (after refresh). Basic: **demo** / **secret**. Events token: `docs-mock-events-token`.

Implementation: `src/docs/mock-api/api-config-mock.ts` (bundled in the Service Worker with `router.ts`).

## See also

- [@get](/docs/decorators/get) — `APIConfiguration` + `Endpoint`
- [@post](/docs/decorators/post) — same configuration model for POST
- [@put](/docs/decorators/put) · [@patch](/docs/decorators/patch) — PUT / PATCH
- [Endpoint](/docs/misc/endpoint) — typed path
- [Local API demos](/docs/misc/docs-mock-api) — offline `serviceURL`
- [Fetch](/core/components/functional/fetch) — attribute table (legacy sonic-fetch)