# Basic Auth

A username and password in the Authorization header - the ubiquitous credential for channels and outgoing connections.

[Video: New Basic Auth definition](https://zatosource-production.b-cdn.net/docs/gfx/security/basic-auth-create.webm?v=1792089418)

Dashboard menu: Security > Basic Auth

## Overview {#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 natively, so it is 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 {#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](https://zato.io/docs/admin/enmasse.html) under the `security` key, with `type: basic_auth` - the fields are in the [enmasse reference](https://zato.io/docs/admin/enmasse-reference.html).

## Inbound channels {#inbound-channels}

Assign a definition to a [REST](https://zato.io/docs/dev/rest/channels.html) or [SOAP](https://zato.io/docs/dev/soap/index.html) channel by selecting **Basic Auth/\<name>** in the channel's security dropdown. From then on, every request to that channel must present the credentials:

```bash
$ curl -u partner.api:partner-password-value http://localhost:11223/api/orders
```

A request without credentials, or with wrong ones, receives a 401 response whose challenge names the definition's realm:

```text
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Basic realm="API"
```

In service code, `self.channel.security.username` names the caller the channel authenticated.

## Default definitions {#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 from an editor](https://zato.io/docs/dev/ide/index.html) and a separate definition for the `/metrics` Prometheus endpoint. Each has a generated password - the details are under [security defaults](https://zato.io/docs/admin/security/defaults.html).

## Security groups and MCP gateways {#security-groups-and-mcp-gateways}

Basic Auth definitions can be members of [API client security groups](https://zato.io/docs/dev/rest/security-groups.html), 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](https://zato.io/docs/ai/mcp/security.html), where the clients are AI agents.

## Outgoing connections {#outgoing-connections}

The same definition drives outgoing calls. When an [outgoing REST connection](https://zato.io/docs/dev/rest/outconns.html) 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 {#rate-limiting}

The **Rate limiting** link next to a definition in its list assigns a [quota tier](https://zato.io/docs/security/quota-tiers.html) or custom [rate limiting](https://zato.io/docs/admin/guide/rate-limit.html) rules to the client holding the credentials - counters are tracked per definition.

## OpenAPI console sign-in {#openapi-console-sign-in}

A Basic Auth definition also signs in to the [OpenAPI console](https://zato.io/docs/dev/rest/openapi-console.html) 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.

## Learn more {#learn-more}

- [Securing channels](https://zato.io/docs/admin/security/channel.html) - Which security types a channel accepts, and how to assign them
- [Securing outgoing connections](https://zato.io/docs/admin/security/outgoing.html) - Credentials Zato presents to the systems it calls
- [API keys](https://zato.io/docs/security/api-keys.html) - Per-client keys in a configurable HTTP header
- [Bearer tokens](https://zato.io/docs/security/bearer-tokens/) - Static tokens and JWTs verified against a JWKS endpoint
- [Security groups](https://zato.io/docs/security/groups.html) - Many API client credentials on one channel or MCP gateway
- [Kerberos (SPNEGO)](https://zato.io/docs/security/kerberos/) - Negotiate authentication from a keytab, with no ticket management
- [mTLS](https://zato.io/docs/security/mtls/) - Client certificates in both directions, matched by fingerprint or DN
- [NTLM](https://zato.io/docs/security/ntlm.html) - Windows domain credentials for outgoing connections
- [WS-Security](https://zato.io/docs/security/ws-security.html) - UsernameToken, X.509 and SAML for SOAP traffic
- [Quota tiers](https://zato.io/docs/security/quota-tiers.html) - Named rate-limit plans assigned to any number of API clients
- [TLS certificates](https://zato.io/docs/admin/security/ssl/) - Your own certificates, the self-signed ones and how to rotate them