API keys
Per-client keys in a configurable HTTP header - inbound matching on channels and outgoing headers from one definition.
Overview
An API key security definition describes a key that travels in an HTTP header of the caller's choosing. One definition serves both directions of traffic:
- Channels - API clients present the key in the configured header and Zato matches it before any service code runs.
- Outgoing - Zato attaches the key in the configured header to every call an outgoing REST connection makes.
Definitions are managed in the dashboard under Security > API keys. Changes take effect immediately, without server restarts.
Definition fields
| Field | Notes |
|---|---|
| Name | A unique name for the definition |
| Header | The HTTP header the key travels in, X-API-Key by default. The default is server-wide and can be redefined with the Zato_API_Key_Name environment variable. |
| API key | The key itself - the exact value clients present and outgoing calls attach |
The definition is exported and imported with enmasse under the security key, with type: apikey - the fields are in the enmasse reference.
Inbound REST channels
Assign a definition to a REST channel by selecting API key/<name> in the channel's security dropdown. From then on, every request to that channel must carry the key in the definition's header:
Matching is an exact, constant-time comparison of the header's value against the definition's key. A request without the header, or with a key that does not match, receives a 401 response.
The header is per definition, so different channels can expect their keys in different headers - a partner integration can use X-Partner-Token while mobile clients stay on X-API-Key.
Security groups and MCP gateways
API key definitions can be members of API client security groups, next to Basic Auth and Bearer token members. A group assigned to a channel accepts a request when any of its members matches the presented credentials.
- Groups are managed under Security > Groups in the dashboard.
- All API key members of one channel's groups share one header name - the first member's header becomes channel-wide and a member with a different header is rejected when the configuration loads.
- Group membership changes are live - adding or removing a member is reflected in enforcement immediately, without restarts.
- Rejections at the group level return 403, unlike direct channel assignments which return 401.
The same definitions and groups also protect MCP gateways, where the clients are AI agents presenting the key on every request.
Outgoing connections
The same definition drives outgoing calls. When an outgoing REST connection uses an API key definition, Zato attaches the key in the configured header to every request the connection makes - there is nothing to add in service code.
Rate limiting
The Rate limiting link next to a definition in its list assigns a quota tier or custom rate limiting rules to the clients holding the key - counters are tracked per definition.
OpenAPI console sign-in
An API key definition also signs in to the OpenAPI console - the definition's name is the username and the key is the password. The signed-in caller receives an OpenAPI document containing only the channels the definition is assigned to, directly or through group membership.