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 belongs to one gateway group. Its username is unique within that group, and consumer operations through the Admin API require the group's gateway_group_id. To use the same caller identity in another group, create a consumer and its credentials in that group as well.

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.

Authorized credential reads can return plaintext keys, passwords, and signing secrets. Encryption at rest does not make those values unavailable through the Admin API. Restrict credential-read permissions and avoid saving full credential responses in logs or shared files.

Authentication Flow

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

1. The client sends a request with credentials (e.g., an apikey header).
2. The gateway executes the corresponding authentication plugin configured on the Route or Service.
3. The plugin validates the credential and maps it to a specific Consumer.
4. Once identified, the gateway applies any plugins configured at the Consumer level.
5. 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.