Consumers and Credentials

A consumer represents the identity of an API caller, such as a developer, a partner application, or an internal service. Define consumers to apply security policies, rate limits, and access control at the identity level rather than only at the route or service level.

Consumer

A consumer belongs to a single gateway group — its username is unique within that gateway group, and creating or reading a consumer through the Admin API requires a gateway_group_id. To give the same identity access across multiple gateway groups, create a separate consumer with the same credentials in each group.

Key fields

Field	Type	Required	Description
`username`	string	Yes	Unique identifier for the consumer. Pattern: `^[a-zA-Z0-9_-]+$`. Max 512 characters.
`desc`	string	No	Description of the consumer.
`labels`	object	No	Key-value pairs for grouping and filtering consumers.
`plugins`	object	No	Plugins applied specifically to this consumer (e.g., `rate-limiting`, `acl`).

Consumer credential

A consumer credential is an authentication token or set of credentials attached to a consumer. One consumer can hold several credentials of different types, so the same identity authenticates with more than one method.

Key fields

Field	Type	Required	Description
`name`	string	Yes	Unique name for the credential.
`plugins`	object	Yes	The authentication plugin configuration. Exactly one plugin is allowed per credential.

Supported credential types

API7 Gateway supports the following authentication methods for consumer credentials:

Type	Description
`key-auth`	An API key passed in a header or query parameter.
`basic-auth`	Standard HTTP Basic Authentication using a username and password.
`hmac-auth`	Enhanced security using signed requests with a key and secret.
`jwt-auth`	Token-based authentication using JSON Web Tokens.

Credential rotation

A consumer can hold more than one credential of the same type at once. That overlap is what makes rotation possible without downtime: add the new credential, let clients move across, then delete the old one. There is no separate rotation API — the overlap window is the mechanism.

Two behaviours worth knowing:

After a successful authentication, the gateway forwards X-Credential-Identifier to the upstream carrying the ID of the credential that matched. Use it to attribute a request to a specific key rather than only to a consumer.
GET /apisix/admin/consumers/{username} never returns credentials inline — the consumer object itself carries no secret material. But GET /apisix/admin/consumers/{username}/credentials/{credential_id} does, and it returns the secret in plaintext (for example, the key-auth key or the basic-auth password), not a hash or a masked value. Anyone with Admin API read access to a consumer's credentials can read the live secret back at any time — treat that access the same way you would treat access to the secret itself, and rotate a credential when it needs to stop being readable rather than assuming the control plane cannot produce it.

Authentication flow

The following diagram illustrates how the gateway processes credentials to identify a consumer:

The client sends a request with credentials (e.g., an apikey header).
The gateway executes the corresponding authentication plugin configured on the route or service.
The plugin validates the credential and maps it to a specific consumer.
Once identified, the gateway applies any plugins configured at the consumer level.
The request is proxied to the upstream service.

Tasks that use this concept

Access Control Lists (ACLs) — restrict API access to specific consumers.
OAuth 2.0 and OIDC — configure token-based authentication.
Configure Basic Authentication
Configure HMAC Authentication
Configure JWT Authentication
Configure Key Authentication

Related concepts

Plugins — explore authentication and other plugin types.