# JWT Auth Configuration

The `jwt-auth` plugin authenticates consumers by validating signed JSON Web Tokens from request headers, query parameters, or cookies before proxying requests.<!-- --> <!-- -->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

  valid value:

  non-empty

  ***

  A unique key that identifies the credential for a consumer.

* secret

  string

  valid value:

  non-empty

  ***

  Shared key used to sign and verify the JWT when the algorithm is symmetric. Required when using `HS256`, `HS384`, or `HS512` as the algorithm.

  The secret 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).

* public\_key

  string

  ***

  Public key used to verify JWTs signed with an asymmetric algorithm. Required for every supported non-HMAC algorithm.

* algorithm

  string

  default: `HS256`

  valid value:

  `HS256`, `HS384`, `HS512`, `RS256`, `RS384`, `RS512`, `ES256`, `ES384`, `ES512`, `PS256`, `PS384`, `PS512`, `EdDSA`

  ***

  Algorithm used to sign and verify the token. The `alg` value in the JWT header must exactly match this configured value; a mismatch is rejected with `401 Unauthorized`.

* exp

  integer

  default: `86400`

  valid value:

  greater than or equal to 1

  ***

  Expiry time of the token in seconds.

  If you are not using APISIX to sign the JWT, this parameter is ignored and you should specify the expiration in the payload when signing the JWT.

* base64\_secret

  boolean

  default: `false`

  ***

  Set to true if the secret is base64 encoded.

* lifetime\_grace\_period

  integer

  default: `0`

  valid value:

  greater than or equal to 0

  ***

  Grace period in seconds. Used to account for clock skew between the server generating the JWT and the server validating the JWT.

### 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: `authorization`

  ***

  The header to get the token from.

* query

  string

  default: `jwt`

  ***

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

* cookie

  string

  default: `jwt`

  ***

  The cookie to get the token from. Lower priority than query.

* hide\_credentials

  boolean

  default: `false`

  ***

  If true, remove the JWT from the source selected for authentication before forwarding upstream. Sources are checked in header, query parameter, then cookie order. Lower-priority duplicates are not removed.

* 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/jwt-auth.md#rate-limit-with-anonymous-consumer) for more details.

* claims\_to\_verify

  array\[string]

  valid value:

  combination of `exp` and `nbf`

  ***

  Claims used to verify that the token is within its allowed time window.

  A nonempty list makes every listed claim required. A token missing a configured claim is rejected.

  When this option is unset or empty, `exp` and `nbf` are validated whenever they are present, but neither claim is required.

  These validation rules were introduced in API7 Enterprise 3.9.14 and 3.10.1, and in APISIX 3.17.0.

* key\_claim\_name

  string

  default: `key`

  ***

  The claim in the JWT payload that identifies the associated secret, such as `iss`.

* store\_in\_ctx

  boolean

  default: `false`

  ***

  If true, store JWT payload in the request context variable `ctx.jwt_auth_payload`. This allows plugins executed after `jwt-auth` on the same request to retrieve and use the payload information. For instance, to retrieve the key in the payload, you can use `ctx.jwt_auth_payload.key`.

  Supported in APISIX and from Enterprise 3.8.9.

* realm

  string

  default: `jwt`

  ***

  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 `jwt-auth`, the 401 response will include the following header:

    ```
    WWW-Authenticate: Bearer realm="jwt-auth"
    ```

  * If `realm` is not configured, the 401 response will include the following header:

    ```
    WWW-Authenticate: Bearer realm="jwt"
    ```

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