API Usage — Headers & Rate Limits

This chapter covers HTTP headers, CORS rules and throttling. Read REST Conventions first.

---

Required headers

Frontend calls (Bearer + enriched)

httpCopy
Authorization: Bearer <keycloak_access_token>
x-enriched-token: <wakastart_token>
Content-Type: application/json

Backend calls (API Key)

httpCopy
x-api-key: sk_live_...
Content-Type: application/json

---

Optional headers

No x-trace-id/x-request-id: these headers are not implemented to date (no occurrence on public-api, backend-for-front, or discovery). For a support incident, provide the timestamp, the route called, and the error response body.

---

CORS

The WakaStart API supports CORS for registered origins. The rules:

• Allowed origins: configured in ALLOWED_ORIGINS on the API side.
• Credentials: Access-Control-Allow-Credentials: true — HttpOnly cookies are transmitted.
• Methods: GET, POST, PUT, PATCH, DELETE, OPTIONS.
• Exposed headers: Retry-After.

Direct calls from the browser: if your frontend calls the API without a proxy, the wakastart_token cookie is HttpOnly and inaccessible from JavaScript. You cannot pass x-enriched-token from the browser without a proxy. Always use a server-side proxy.

---

Idempotency

GET, PUT, and DELETE operations are idempotent. For POST:

• Invitation creation: if a PENDING invitation already exists for the same email + Customer, the API responds 409 Conflict. It is safe to retry after a network failure.
• Enrichment: /api/auth/enrich is idempotent for the same access_token within its validity period.
• Token refresh: /api/auth/token/refresh generates a new token on every call. Do not call it in parallel.

---

Rate limiting

The API applies three levels of throttling:

Endpoint-specific limits

429 Response:

jsonCopy
{ "statusCode": 429, "message": "Too Many Requests" }

The Retry-After header indicates the wait time in seconds.

---

Exponential backoff

typescriptCopy
async function fetchWithRetry(
  url: string,
  options: RequestInit,
  maxRetries = 3
): Promise<Response> {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const res = await fetch(url, options);
    if (res.status !== 429) return res;

    const retryAfter = parseInt(res.headers.get("Retry-After") ?? "1", 10);
    const delay = retryAfter * 1000 * Math.pow(2, attempt);
    await new Promise(r => setTimeout(r, delay));
  }
  throw new Error("Rate limit exceeded after retries");
}

---

Checking rights from your backend

httpCopy
POST /api/token/authorize
x-api-key: sk_live_...
Content-Type: application/json

{
  "token": "eyJ...",
  "checks": {
    "adminLevel": { "requiredLevel": "CustomerAdmin" },
    "roles": { "roles": ["CONFIG"], "mode": "any" },
    "appRights": { "rights": ["users.create"], "mode": "all" }
  }
}

jsonCopy
{
  "authorized": true,
  "details": {
    "adminLevel": { "hasLevel": true,  "actualLevel": "NetworkAdmin" },
    "roles":      { "hasRoles": true,  "matchedRoles": ["CONFIG"] },
    "appRights":  { "hasRights": true, "missingRights": [] }
  }
}

---

Best practices

• Headers don't stack: a call with both x-api-key AND Authorization: Bearer will see the API key take precedence.
• Log the error response body on 5xx (route, method, statusCode, message): in the absence of x-request-id, this is what lets support find the incident.
• Respect Retry-After: don't ignore this header, it protects the API's stability.

Common pitfalls

• Parallel calls to refresh: if several requests expire at the same time and all attempt a simultaneous refresh, only one succeeds. Implement a client-side mutex.
• Rate limit on tests: in CI, a batch of tests can trigger the short-duration rate limit. Add delays between integration tests.

Go further

• HTTP errors: 429 and 401 codes in detail
• Security best practices: tokens, secrets, HTTPS