Access Control
Zerq gives you fine-grained control over who can call your APIs, how they authenticate, and how much traffic they can send.
The access control model
Access control in Zerq works in layers:
- Client: defines the API consumer identity and collection assignments.
- Profile: defines auth method, optional method restrictions, and optional IP allowlist.
- Policy: applies request rate limits and long-window quotas.
- Collection access list: constrains which API products the client can invoke.
Clients
A Client is an entity (app, service, partner, or AI agent) that consumes your APIs. You create a client for each distinct consumer.
Every client has:
- A list of collections it can access
- One or more profiles (auth configurations)
- An optional policy (rate limits)
Profiles
A Profile is the authentication configuration for a client. One client can have multiple profiles — for example, a read-only profile with liberal limits and a write profile with strict limits.
Profiles define:
- Auth type: how the client proves its identity
- Allowed methods: optional restriction (e.g., GET only)
- Allowed IPs: optional IP allowlist
- Status: active or inactive
Policies
A Policy defines rate limits and usage quotas. Attach a policy to a client to restrict how many requests they can send per minute, hour, day, or month.
Authentication flow
Every request to the gateway must include:
X-Client-ID: <client-id>
X-Profile-ID: <profile-id>
Plus authentication based on the profile's auth type:
# Token auth
Authorization: Bearer <token>
# JWT auth
Authorization: Bearer <jwt>
# OIDC auth
Authorization: Bearer <oidc-jwt>
# mTLS: no extra header — client certificate in TLS handshake
Zerq validates:
- The client exists and is active
- The profile exists, is active, and belongs to the client
- The client has access to the requested collection
- The authentication credential is valid
- The request is within rate limits
Access denied responses
| Scenario | HTTP Status | Error code |
|---|---|---|
| Missing client/profile headers | 401 | unauthorized |
| Invalid token | 401 | invalid_token |
| Client does not have collection access | 403 | forbidden |
| Rate limit exceeded | 429 | rate_limit_exceeded |
| Quota exceeded | 429 | quota_exceeded |
| IP not in allowlist | 403 | ip_not_allowed |
| Method not allowed by profile | 405 | method_not_allowed |
Next steps
- Clients — create and manage API clients
- Profiles — configure authentication per client
- Policies (Rate Limits & Quotas) — set rate limits and quotas
- Authentication Methods — token, JWT, OIDC, mTLS