# Implement JWT Authentication

JWT authentication is a secure and stateless method for authenticating API clients with a signed JSON Web Token. The token can contain claims such as user identity and roles, allowing an API to validate a request without querying an authentication database. This approach works well for distributed applications that need lightweight authentication. Because a token remains valid until it expires, use short expiration times or implement token revocation for sensitive APIs.

In this guide, you will implement a scenario where there are two consumers using [JWT authentication](https://docs.api7.ai/hub/jwt-auth.md) to authenticate with APISIX, each with a different rate limiting quota. Once implemented, consumers should have access to the upstream service and forward consumer IDs to the upstream service, opening up options for additional business logic.

## Prerequisite(s)[​](#prerequisites "Direct link to Prerequisite(s)")

* Install [Python 3](https://www.python.org/downloads/) to issue the example JWTs locally.
* If you use the Admin API examples and authentication is enabled, export an admin-role key as `ADMIN_API_KEY`. Configure the key under `deployment.admin.admin_key`. The Docker quickstart disables authentication for local evaluation; keep it enabled in production.

## Create Consumers[​](#create-consumers "Direct link to Create Consumers")

A consumer is an application or a developer who consumes the API. You should always create consumers when using APISIX built-in authentication methods.

Create a consumer `johndoe` with an optional custom ID and a rate limiting quota of one request in a 30-second window:

```
curl "http://127.0.0.1:9180/apisix/admin/consumers" -X PUT \

  -H "X-API-KEY: ${ADMIN_API_KEY}" \

  -d '{

    "username": "johndoe",

    "labels": {

      "custom_id": "john-doe-junior"

    },

    "plugins": {

      "limit-count": {

        "count": 1,

        "time_window": 30,

        "rejected_code": 429

      }

    }

  }'
```

The custom ID will be forwarded to the upstream service, should you wish to implement additional business logic.

Create another consumer `janedoe` with an optional custom ID and a rate limiting quota of two requests in a 30-second window:

```
curl "http://127.0.0.1:9180/apisix/admin/consumers" -X PUT \

  -H "X-API-KEY: ${ADMIN_API_KEY}" \

  -d '{

    "username": "janedoe",

    "labels": {

      "custom_id": "jane-doe-senior"

    },

    "plugins": {

      "limit-count": {

        "count": 2,

        "time_window": 30,

        "rejected_code": 429

      }

    }

  }'
```

## Create Consumer Credentials[​](#create-consumer-credentials "Direct link to Create Consumer Credentials")

Credentials are used to configure authentication credentials associated with consumers.

Create `jwt-auth` credential for `johndoe`:

```
curl "http://127.0.0.1:9180/apisix/admin/consumers/johndoe/credentials" -X PUT \

  -H "X-API-KEY: ${ADMIN_API_KEY}" \

  -d '{

    "id": "cred-john-jwt-auth",

    "plugins": {

      "jwt-auth": {

        "key": "john-key",

        "secret": "john-hs256-secret-that-is-very-long"

      }

    }

  }'
```

Create `jwt-auth` credential for `janedoe`:

```
curl "http://127.0.0.1:9180/apisix/admin/consumers/janedoe/credentials" -X PUT \

  -H "X-API-KEY: ${ADMIN_API_KEY}" \

  -d '{

    "id": "cred-jane-jwt-auth",

    "plugins": {

      "jwt-auth": {

        "key": "jane-key",

        "secret": "jane-hs256-secret-that-is-very-long"

      }

    }

  }'
```

## Create a Route[​](#create-a-route "Direct link to Create a Route")

Create a route and enable `jwt-auth`:

```
curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \

  -H "X-API-KEY: ${ADMIN_API_KEY}" \

  -d '{

    "id": "jwt-auth-route",

    "uri": "/anything",

    "plugins": {

      "jwt-auth": {"claims_to_verify": ["exp"]}

    },

    "upstream": {

      "type": "roundrobin",

      "nodes": {

        "httpbin.org:80": 1

      }

    }

  }'
```

## Issue JWT[​](#issue-jwt "Direct link to Issue JWT")

Issue both HS256 tokens locally so the signing secrets stay out of third-party websites. Each token below carries the consumer's key, its issue time, and an expiration five minutes later. Save the script as `issue-jwts.py`:

issue-jwts.py

```
import base64

import hashlib

import hmac

import json

import shlex

import time



def encode(value):

  data = json.dumps(value, separators=(",", ":")).encode()

  return base64.urlsafe_b64encode(data).rstrip(b"=").decode()



now = int(time.time())

for variable, key, secret in [

  ("john_jwt_token", "john-key", "john-hs256-secret-that-is-very-long"),

  ("jane_jwt_token", "jane-key", "jane-hs256-secret-that-is-very-long"),

]:

  header = encode({"alg": "HS256", "typ": "JWT"})

  payload = encode({"key": key, "iat": now, "exp": now + 300})

  message = f"{header}.{payload}"

  signature = hmac.new(secret.encode(), message.encode(), hashlib.sha256).digest()

  encoded_signature = base64.urlsafe_b64encode(signature).rstrip(b"=").decode()

  print(f"export {variable}={shlex.quote(message + '.' + encoded_signature)}")
```

Load fresh tokens into the current shell:

```
eval "$(python3 issue-jwts.py)"
```

The route explicitly requires `exp` through `claims_to_verify`. When that list is unset or empty, `exp` and `nbf` are checked only when present. The token header's `alg` must match the credential's configured algorithm; an algorithm mismatch is rejected before signature verification. Regenerate the tokens if verification takes longer than five minutes.

## Verify[​](#verify "Direct link to Verify")

Send a request to the route with `john`'s key:

```
curl -i "http://127.0.0.1:9080/anything" -H "Authorization: ${john_jwt_token}"
```

You should see an `HTTP/1.1 200 OK` response similar to the following:

```
{

  "args": {}, 

  "data": "", 

  "files": {}, 

  "form": {}, 

  "headers": {

    "Accept": "*/*", 

    "Authorization": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJrZXkiOiJqb2huLWtleSIsIm5iZiI6MTcyOTEzMjI3MX0.TgoM2efMEaSX7KrIWujGLGK5dpPGS2nbaiinmVVjKKw", 

    "Host": "127.0.0.1", 

    "User-Agent": "curl/8.6.0", 

    "X-Amzn-Trace-Id": "Root=1-6873b51b-5502cfcd72380323266c22e8", 

    "X-Consumer-Custom-Id": "john-doe-junior", 

    "X-Consumer-Username": "johndoe", 

    "X-Credential-Identifier": "cred-john-jwt-auth", 

    "X-Forwarded-Host": "127.0.0.1"

  }, 

  ...

}
```

Let the earlier verification request's 30-second quota window expire, then generate three requests to the route with `john`'s key:

```
sleep 31

resp=$(seq 3 | xargs -I{} curl "http://127.0.0.1:9080/anything" -H "Authorization: ${john_jwt_token}" -o /dev/null -s -w "%{http_code}\n") && \

  count_200=$(echo "$resp" | grep "200" | wc -l) && \

  count_429=$(echo "$resp" | grep "429" | wc -l) && \

  echo "200": $count_200, "429": $count_429
```

You should see the following response, showing that out of the 3 requests, 1 request was successful while the others were rejected:

```
200:    1, 429:    2
```

Generate three requests to the route with `jane`'s key:

```
resp=$(seq 3 | xargs -I{} curl "http://127.0.0.1:9080/anything" -H "Authorization: ${jane_jwt_token}" -o /dev/null -s -w "%{http_code}\n") && \

  count_200=$(echo "$resp" | grep "200" | wc -l) && \

  count_429=$(echo "$resp" | grep "429" | wc -l) && \

  echo "200": $count_200, "429": $count_429
```

You should see the following response, showing that out of the 3 requests, 2 requests were successful while the other was rejected:

```
200:    2, 429:    1
```

Finally, send a request with an invalid key:

```
curl -i "http://127.0.0.1:9080/anything" -H 'Authorization: somewrongkey'
```

You should see an `HTTP/1.1 401 Unauthorized` response with the following message:

```
{"message":"JWT token invalid"}
```

## Next Steps[​](#next-steps "Direct link to Next Steps")

You have now learned how to implement basic authentication. APISIX supports other built-in authentication methods, such as [key authentication](https://docs.api7.ai/apisix/how-to-guide/authentication/implement-key-auth.md), [basic authentication](https://docs.api7.ai/apisix/how-to-guide/authentication/implement-basic-auth.md), and [HMAC authentication](https://docs.api7.ai/apisix/how-to-guide/authentication/implement-hmac-auth.md).
