Key Concepts
Zerq is built around a small set of core concepts. Understanding these will make everything else click.
Collections
A Collection is a logical grouping of related API endpoints, typically representing one backend service.
Think of a Collection like an API product:
- Collection name:
Payments API - Base path:
/payments - Target endpoint:
https://internal-payments.example.com - Contained proxies:
GET /transactions,POST /charge,GET /refunds/{id}
Collections have:
- A base path — the prefix that clients use when calling through the gateway
- A target endpoint — the backend URL requests are forwarded to
- Optional credentials — for authenticating with the backend
- Optional headers — added to every forwarded request
- A status (draft or published)
Proxies
A Proxy is an individual endpoint definition within a Collection.
Each proxy maps an incoming request pattern to the backend:
| Field | Description |
|---|---|
| Path | The URL path relative to the collection base path |
| HTTP Methods | Which methods are allowed (GET, POST, PUT, DELETE, PATCH) |
| Target Path | The path sent to the backend (can differ from the incoming path) |
| Parameters | Path params, query params with types and validation |
| Schemas | Request body schema and response body schema |
| Workflow | Optional processing pipeline executed for each request |
Proxies go through a draft → published lifecycle. Only published proxies are visible in the Developer Portal and accept live traffic.
Clients
A Client represents an external application or service that consumes your APIs.
A client has:
- An identity (name, email)
- A list of Collections it can access
- One or more Profiles (authentication credentials and access settings)
- An optional Policy (rate limits and quotas)
- A developer portal access toggle
Examples of clients:
- A mobile app
- A partner's backend service
- An AI assistant
- An internal microservice
Profiles
A Profile is an access configuration attached to a Client. It defines how that client authenticates and what it can do.
Each profile has:
- An auth type:
token,jwt,oidc,mtls, ornone - The actual credential (token value, JWT config, certificate, etc.)
- Allowed HTTP methods (optional — restrict to GET only, for example)
- Allowed IP addresses (optional allowlist)
- Status (active/inactive)
A client can have multiple profiles — for example, a sandbox profile with no rate limits and a production profile with strict quotas.
When a client calls the gateway, it identifies itself with two headers:
X-Client-ID: <client-id>
X-Profile-ID: <profile-id>
Policies
A Policy defines usage limits that can be attached to clients.
There are two tiers:
| Type | Description | Example intervals |
|---|---|---|
| Rate limit | Short-term request throttling | 1m, 5m, 1h |
| Quota | Long-term usage cap | 1d, 7d, 30d |
Example policy: "Max 100 requests per minute, max 50,000 per month."
When a client exceeds a limit, the gateway returns 429 Too Many Requests with a clear error message.
Credentials
Credentials are securely stored secrets used by the gateway to authenticate with backend services.
They are separate from client credentials (which control client access to the gateway). Backend credentials control gateway access to your upstream services.
Supported types:
- API Key
- Basic Auth (username/password)
- OAuth2 Client Credentials
- mTLS certificates
- Database connections (MongoDB, PostgreSQL, SQL Server, Oracle)
- Message queues (Kafka)
- Email services (SMTP, SendGrid)
- Cache (Redis)
Credentials are encrypted at rest and can reference environment variables so secrets never appear in the UI.
Workflows
A Workflow is an optional processing pipeline attached to a specific Proxy.
Instead of simple pass-through routing, a workflow can:
- Transform the request before forwarding it
- Call multiple backends and merge results
- Query a database and enrich the response
- Apply conditional logic and branching
- Send notifications (email, Kafka)
- Generate or validate JWT tokens
- Execute custom JavaScript
Workflows are defined as a graph of Nodes connected by Edges. Every workflow starts with an http_trigger node (the incoming request) and ends with a response_node (the response sent to the client).
How they relate
| Layer | Relationship |
|---|---|
| Collection -> Proxies | A collection groups endpoint definitions that share a base path and upstream target |
| Proxy -> Workflow | A proxy can optionally run a workflow graph before returning a response |
| Client -> Profile | A client uses one profile per request to define auth and access behavior |
| Client -> Policy | A policy enforces rate/quota limits for the client |
| Gateway runtime | Applies auth, policy, routing, and logging on every request |
Glossary
| Term | Meaning |
|---|---|
| Collection | A group of related proxies pointing to one backend service |
| Proxy | An individual API endpoint definition |
| Client | An application or service consuming the gateway |
| Profile | Authentication configuration for a client |
| Policy | Rate limit and quota rules |
| Credential | Secrets for authenticating with backend services |
| Workflow | Node-based request processing pipeline on a proxy |
| MCP | Model Context Protocol — how AI agents discover and call APIs |
| Developer Portal | Self-service web UI for API consumers |
Next steps
- Quickstart — create your first collection, proxy, and client
- Architecture — understand how Zerq components fit together
- Choose Your Path — role-specific starting points