CORS and the playground
The interactive "try it" playground in these docs calls api.bimpe.ai directly from the browser using the API key you enter in the UI. Because the request originates from a different origin than the API, the browser enforces the CORS protocol — and the API must respond with the appropriate CORS headers for the request to succeed.
CORS configuration is an API-side prerequisite. Without the correct response headers, every playground request will be blocked by the browser before it reaches your application code. The API key still authorizes the request — CORS is a browser read-permission mechanism, not an authentication layer.
Required response headers
The API must return these headers on every response to a cross-origin request:
Access-Control-Allow-Origin: <docs-origin>
Access-Control-Allow-Methods: GET, POST, PATCH, DELETE, OPTIONS
Access-Control-Allow-Headers: Authorization, X-Api-Key, Content-Type, Idempotency-Key, X-Request-Id
Access-Control-Expose-Headers: X-Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, Retry-AfterAccess-Control-Allow-Origin must match the requesting origin exactly. The docs are served from three origins that need to be permitted:
- Production docs domain (e.g.
https://docs.bimpe.ai) - Preview / staging deployment URL
http://localhost:3000for local development
Most frameworks let you supply an allowlist and will reflect the matching origin automatically.
Access-Control-Expose-Headers is needed so the browser makes the rate-limit and retry headers visible to JavaScript. Without it, X-RateLimit-* and Retry-After are readable only by the browser's CORS machinery, not by the playground UI.
Preflight handling
Authorization is a non-simple header, so the browser sends a preflight OPTIONS request before every state-changing call. The API must respond to OPTIONS on every path with 204 No Content and the headers above. If the preflight is rejected or times out, the actual request never fires.