API reference
Three API surfaces matter to integrators: the data plane that proxies your traffic, the consumer portal API used by the developer portal, and the consumer auth endpoints that issue portal sessions.
Data plane — /api/*
All proxied traffic flows through paths under /api/*. The gateway matches the path against your tenant's routes, authenticates the x-api-key header, applies rate limits and resilience policies, and forwards the request to the upstream service.
curl -i -H "x-api-key: gw_live_…" \
https://gateway.example.com/api/v1/ordersError envelope
When the gateway itself rejects a request, it answers with a JSON envelope containing a stable machine-readable code:
| Code | Meaning |
|---|---|
| ROUTE_NOT_FOUND | No route matches the request path |
| API_KEY_MISSING | The x-api-key header was not sent |
| API_KEY_INVALID | The key is unknown, revoked, or expired |
| BINDING_FORBIDDEN | The key is valid but not bound to this service |
| METHOD_NOT_ALLOWED | The route does not allow this HTTP method |
| RATE_LIMITED | The key exceeded its requests-per-second limit |
| CIRCUIT_OPEN | The upstream's circuit breaker is open |
| UPSTREAM_UNAVAILABLE | The upstream could not be reached |
Response headers
The gateway annotates responses with rate-limit and tracing headers:
| Header | Description |
|---|---|
| x-ratelimit-limit | The key's configured request limit |
| x-ratelimit-remaining | Requests remaining in the current window |
| retry-after | Seconds to wait after a RATE_LIMITED response |
| x-correlation-id | Request id — quote it when reporting issues |
Example — rate-limited request
A request that exceeds its per-key limit receives HTTP 429 with the envelope and headers:
HTTP/1.1 429 Too Many Requests
x-ratelimit-limit: 50
x-ratelimit-remaining: 0
retry-after: 1
x-correlation-id: 9f6c2b1e-…
{
"error": {
"code": "RATE_LIMITED",
"message": "API key exceeded its request rate limit"
}
}Consumer portal API
The developer portal is backed by these endpoints. They require a consumer session token (Bearer) obtained from the consumer auth endpoints below.
| Endpoint | Description |
|---|---|
| GET /consumer/catalogue | Published services available to this consumer |
| GET /consumer/keys | List the consumer's API keys |
| GET /consumer/keys/{id}/usage?days=N | Usage analytics for one key over the last N days |
| GET / PUT /consumer/notifications | Read and update notification preferences |
| GET / POST /consumer/requests | List and create access requests |
| GET / PUT /consumer/profile | Read and update the consumer profile |
Consumer auth — /consumer-auth/*
Portal sessions are issued and inspected here:
| Endpoint | Description |
|---|---|
| POST /consumer-auth/signup | Create a consumer account |
| POST /consumer-auth/login | Exchange email and password for a session token |
| GET /consumer-auth/me | Return the authenticated consumer's account |