# customers-api

Kong routing/policy layer for the **customers** slice of
`classic-models-api` (see `/Users/stephanetailland/git/classic-models-api`),
split out per the DDD decomposition in `../kong-konnect-deployment-strategy.md`.
The backend itself stays a single monolith — only Kong does the domain
split. Same role as `../catalog-api` plays for `catalog`, structure
deliberately mirrored.

**REST only for now** (`kong/rest/`) — 8 routes covering
`Customer` plus its `orders`/`payments` sub-resources (cross-domain reads,
same backend). No MCP surface yet, unlike `catalog-api` — add one
(`kong/mcp/`, a `mcp-customers` Keycloak audience/client-scope, an entry in
`dataplane-customers`'s `JWT_AUDIENCE_WHITELIST`) the same way if/when this
domain needs an MCP entry point.

| Route | Method | Backend path |
|---|---|---|
| `/customers/v1/customers/` | GET, POST | `/classic-models/api/v1/customers/` |
| `/customers/v1/customers/{customernumber}/` | GET, PUT, PATCH, DELETE | `/classic-models/api/v1/customers/{customernumber}/` |
| `/customers/v1/customers/{customernumber}/orders/` | GET | `/classic-models/api/v1/customers/{customernumber}/orders/` |
| `/customers/v1/customers/{customernumber}/payments/` | GET | `/classic-models/api/v1/customers/{customernumber}/payments/` |

## Auth

`openid-connect` on the REST service, `audience_required`/token-exchange
target = `classic-models-api` (`BACKEND_AUDIENCE`). Unlike `catalog-api`,
there's no MCP hop minting an intermediate `customers-api`-audience token
today — a caller gets one directly via `token-exchange-broker`
(`customers-api-audience` client scope, added there 2026-08-23) and calls
these routes with it; the REST-layer plugin then exchanges that token again
to `classic-models-api` before it reaches the backend, same second-hop
pattern as `catalog-api`'s REST layer. IdP is the **local** Keycloak
(`https://keycloak.sttlab.local/realms/classic-models`) — see
`../dataplane-customers/README.md` and `../STATUS.md` sections 15/16 for
why (platform-wide migration off the VPS Keycloak, not customers-specific).
`consumer_claims`/`consumer_by` map the JWT `sub` to a Kong Consumer for
per-consumer rate limiting, same as `catalog-api`.

## Other policies

Per-consumer rate limiting, response caching (GET/HEAD), audit log
(`http-log`, endpoint still a placeholder — no real log collector in this
lab, same caveat as `catalog-api`).

## Structure

Same three-piece `dev/` layout as `catalog-api`: `dev/gitrepository.yaml` +
`dev/flux-kustomization.yaml` (deploys `./kong` into the `customers`
namespace's dev environment, `dependsOn` `dataplane-customers`'s Gateway
Kustomization), `dev/externalsecret.yaml` (git deploy key),
`dev/token-exchange-broker-externalsecret.yaml` (the broker's client
secret). `kong/rest/` — service, routes, path-rewrites, auth/rate-
limit/cache/audit-log policies and their bindings.

**Not deployed yet — blocked on one external step**: the gitea repo
`kong-customers-api.git` this `dev/gitrepository.yaml` points at doesn't
exist (`https://gitea.sttlab.eu/stt/kong-customers-api` → 404 as of
2026-08-23). A dedicated deploy keypair was generated and stored in Vault
(`kong-v2/customers-api/git-deploy-key`) as if it did — once the repo
exists and that key is registered as its deploy key, this content needs to
be pushed to it, then `dev/gitrepository.yaml` + `dev/flux-kustomization.yaml`
+ the two `dev/*externalsecret.yaml` files applied to the cluster.
`kong-v2/customers-api/token-exchange-broker` (the broker's client secret,
copied from the live local Keycloak) is already stored in Vault and ready.