# Key Auth Configuration

The `key-auth` plugin allows clients to authenticate using an authentication key before accessing upstream resources, enhancing API security measures.<!-- --> <!-- -->Configuration covers credential fields and route and service fields.

## Parameters[​](#parameters "Direct link to Parameters")

See plugin [common configurations](https://docs.api7.ai/apisix/reference/plugin-common-configurations.md) for configuration options available to all plugins.

### Credentials[​](#credentials "Direct link to Credentials")

The following are plugin attributes available for configurations on [credentials](https://docs.api7.ai/apisix/key-concepts/credentials.md).

* key

  string

  required

  ***

  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](https://developer.hashicorp.com/vault/docs/secrets/kv), and reference it using the `$secret://` prefix. These gateway references are resolved at runtime. ADC `${NAME}` interpolation is different because ADC resolves it while loading the configuration file, before synchronization. For more information, see [secrets](https://docs.api7.ai/apisix/key-concepts/secrets.md).

### Routes or Services[​](#routes-or-services "Direct link to Routes or Services")

The following are plugin attributes available for configurations on [routes](https://docs.api7.ai/apisix/key-concepts/routes.md) or [services](https://docs.api7.ai/apisix/key-concepts/services.md).

* header

  string

  default: `apikey`

  ***

  The header to get the key from.

* query

  string

  default: `apikey`

  ***

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

* hide\_credentials

  boolean

  default: `false`

  ***

  If true, remove the key from the source selected for successful authentication before forwarding upstream. The header has priority over the query parameter, and a lower-priority duplicate is not removed. Before falling back to `anonymous_consumer`, the gateway removes invalid credentials from both sources. Invalid-credential removal was introduced in API7 Enterprise 3.9.14 and 3.10.1, and in APISIX 3.17.0.

* anonymous\_consumer

  string

  ***

  Anonymous consumer name. If configured, allow anonymous users to bypass the authentication. See [Rate Limit with Anonymous Consumer](https://docs.api7.ai/hub/key-auth.md#rate-limit-with-anonymous-consumer) for more details.

* realm

  string

  default: `key`

  ***

  Realm in the [`WWW-Authenticate`](https://datatracker.ietf.org/doc/html/rfc7235#section-4.1) 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.
