API Gateway
The Zerq API Gateway is the runtime layer that receives every inbound API request from clients, enforces access control, applies rate limiting and quotas, optionally runs a workflow, and forwards the request to your backend.
What this page covers
- Required request headers
- How the gateway authenticates and authorizes each request
- Rate limiting and quota enforcement
- Streaming and SSE support
- IP and method restrictions
- Common response status codes
Required request headers
Every request to the gateway must include two identity headers in addition to any auth credentials:
| Header | Required | Description |
|---|---|---|
X-Client-ID | Always | MongoDB ObjectID of the API client |
X-Profile-ID | Always | MongoDB ObjectID of the access profile under that client |
Authorization | When authType is token, jwt, or oidc | Bearer <credential> |
For mtls auth, the client certificate is validated at the TLS layer — no Authorization header is needed.
For none auth, no Authorization header is needed; X-Client-ID and X-Profile-ID alone identify the caller.
Example request:
curl https://gateway.yourcompany.com/v1/products \
-H "X-Client-ID: 66a1b2c3d4e5f6a7b8c9d0e1" \
-H "X-Profile-ID: 66a1b2c3d4e5f6a7b8c9d0e2" \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
Auth enforcement sequence
The gateway runs the following checks in order on every request. A failure at any step returns the error immediately — later steps are not evaluated.
Authentication methods at the gateway
| Auth Type | How the credential is sent | Validation |
|---|---|---|
token | Authorization: Bearer <static-token> | HMAC comparison against stored token |
jwt | Authorization: Bearer <JWT> | Signature verified with client/profile-scoped secret |
oidc | Authorization: Bearer <OIDC-access-token> | Verified via JWKS endpoint of configured OIDC issuer |
mtls | Client TLS certificate | Validated at TLS termination; no Authorization header needed |
none | No credential | Identity from headers only; use only on internal or test routes |
To configure the auth type for a profile, go to Access Control → Profiles → Auth Management in the management UI, or use the Auth Management UI guide.
Rate limiting and quotas
Policies attach a two-tier limit to a client:
| Tier | Config fields | Window examples |
|---|---|---|
| Rate limit | rate_limit_requests + rate_limit_interval | 100 requests per 1m |
| Quota | quota_requests + quota_interval | 50000 requests per 30d |
When either limit is exceeded the gateway returns 429 Too Many Requests with a Retry-After header.
Limits are enforced per client (not per profile). All profiles under the same client share the same policy bucket.
See Policies for how to create and assign a policy.
IP and method restrictions
Both restrictions are optional and configured per profile:
allowedIPs— list of exact IPs or CIDR ranges. Empty list = allow all.allowedMethods— list of HTTP methods (GET,POST, etc.). Empty list = allow all.
A mismatch returns 403 Forbidden.
Streaming and SSE
The gateway detects streaming responses and disables compression, caching, and etag middleware automatically when:
Accept: text/event-streamis present in the requestX-Gateway-Streaming: 1header is set?streaming=1query parameter is present
Set streaming: true on the proxy definition in the management UI to opt in at the proxy level.
Common response codes
| Code | Meaning | Common cause |
|---|---|---|
400 | Bad request | Malformed X-Client-ID or X-Profile-ID (not a valid ObjectID) |
401 | Unauthorized | Client/profile not found, inactive, or credential invalid |
403 | Forbidden | IP not in allowlist, HTTP method not allowed, or client lacks access to the collection |
404 | Not found | No proxy path matches the request path |
429 | Too many requests | Rate limit or quota exceeded |
502 | Bad gateway | Backend returned an error or is unreachable |
Related docs
- Profiles and Auth Headers — how to find your client ID, profile ID, and token
- Authentication Methods — configure auth type per profile
- Policies — set rate limits and quotas
- Request Logs — inspect every gateway request
- Troubleshooting — debug common gateway errors