Consumers and Credentials
A Consumer represents the identity of an API caller, such as a developer, a partner application, or an internal service. By defining Consumers, you can apply security policies, rate limits, and access control at the identity level rather than just at the route or service level.
Consumer
A Consumer is a global entity in API7 Gateway that can be used across different Gateway Groups.
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. A single Consumer can have multiple credentials of different types, allowing for flexible authentication methods.
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 | The simplest method, using 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. |
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
apikeyheader). - 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.
Next steps
- Access Control Lists — restrict API access to specific consumers.
- OAuth/OIDC Authentication — configure token-based authentication.
- Plugins — explore authentication and other plugin types.