Basic Auth
A username and password in the Authorization header - the ubiquitous credential for channels and outgoing connections.
Overview
A Basic Auth security definition describes a username and password sent in the HTTP Authorization header, as defined by RFC 7617. It is the credential type that every HTTP client library and every command-line tool supports out of the box, which makes it the usual choice when you issue credentials to API clients. One definition serves both directions of traffic:
- Channels - API clients authenticate to REST and SOAP channels with the definition's username and password.
- Outgoing - Zato presents the credentials to remote systems that an outgoing REST connection calls.
Definitions are managed in the dashboard under Security > Basic Auth. Changes take effect immediately, without server restarts.
Definition fields
| Field | Notes |
|---|---|
| Name | A unique name for the definition |
| Username | The username API clients or remote systems expect |
| Realm | The realm reported in the 401 challenge of a channel, API by default |
| Password | The password - generated when left empty, never a published default |
The definition is exported and imported with enmasse under the security key, with type: basic_auth - the fields are in the enmasse reference.
Inbound channels
Assign a definition to a REST or SOAP channel by selecting Basic Auth/<name> in the channel's security dropdown. From then on, every request to that channel must present the credentials:
A request without credentials, or with wrong ones, receives a 401 response whose challenge carries the definition's realm:
In service code, self.channel.security.username names the caller the channel authenticated.
Default definitions
A new environment ships with Basic Auth definitions for its own APIs - among them admin.invoke for the dashboard's service invoker, ide_publisher for deployments straight from an editor and a separate definition for the /metrics Prometheus endpoint. Each has a generated password - the details are under security defaults.
Security groups and MCP gateways
Basic Auth definitions can be members of API client security groups, next to API key and Bearer token members. A group assigned to a channel accepts a request when any of its members matches the presented credentials - each partner keeps its own username and password, and revoking one partner's access is removing its definition from the group.
- Groups are managed under Security > Groups in the dashboard.
- 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 with the realm challenge.
The same definitions and groups also protect MCP gateways, where the clients are AI agents.
Outgoing connections
The same definition drives outgoing calls. When an outgoing REST connection uses a Basic Auth definition, Zato adds the Authorization header with the definition's credentials 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 client holding the credentials - counters are tracked per definition.
OpenAPI console sign-in
A Basic Auth definition also signs in to the OpenAPI console with its username and password. The signed-in caller receives an OpenAPI document containing only the channels the definition is assigned to, directly or through group membership.