Key Auth Configuration

Configuration reference for the Key Auth plugin (`key-auth`): the parameters on credentials and routes or services, each attribute with its type, whether it is required, its default and its accepted values.

Parameters

See plugin common configurations (opens in Apache APISIX docs) for configuration options available to all plugins.

Credentials

The following are plugin attributes available for configurations on credentials (opens in Apache APISIX docs).

key — string · required · since APISIX 1.2 · API7 Gateway 3.2.16.3

A unique key that identifies the credential for a consumer. The key is encrypted with AES before being stored in etcd. You can also store it in an environment variable and reference it using the env:// prefix, or in a secret manager such as HashiCorp Vault's KV secrets engine, and reference it using the secret:// prefix. For more information, see secrets (opens in Apache APISIX docs).

Routes or Services

The following are plugin attributes available for configurations on routes (opens in Apache APISIX docs) or services (opens in Apache APISIX docs).

header — string · optional · default: apikey · since APISIX 2.6 · API7 Gateway 3.2.16.3

The header to get the key from.

query — string · optional · default: apikey · since APISIX 2.8 · API7 Gateway 3.2.16.3

The query string to get the key from. Lower priority than header.

hide_credentials — boolean · optional · default: false · since APISIX 2.14.1 · API7 Gateway 3.2.16.3

If true, remove the configured credential header and query parameter before forwarding upstream. Before falling back to anonymous_consumer, the gateway also removes invalid credentials. Invalid-credential removal was introduced in API7 Enterprise 3.9.14 and 3.10.1, and in APISIX 3.17.0.

anonymous_consumer — string · optional · since APISIX 3.12.0 · API7 Gateway 3.2.16.3

Anonymous consumer name. If configured, allow anonymous users to bypass the authentication. See Rate Limit with Anonymous Consumer for more details.

realm — string · optional · default: key · since APISIX 3.15.0 · API7 Gateway 3.9.2

Realm in the WWW-Authenticate response header returned with a 401 Unauthorized response due to authentication failure. For example:

If realm is set to key-auth, the 401 response will include the following header:
```
WWW-Authenticate: apikey realm="key-auth"
```
If realm is not configured, the 401 response will include the following header:
```
WWW-Authenticate: apikey realm="key"
```

This parameter is available in API7 Enterprise version 3.9.2 and later, and in Apache APISIX version 3.15.0 and later.