For the complete documentation index, see llms.txt. Markdown versions of all docs pages are available by appending .md to any docs URL.

Control which requests are allowed to reach your backends using authorization policies with Allow, Require, and Deny actions.

Authorization policies in agentgateway let you control which requests are allowed to reach your backends. Policies apply across all traffic types — HTTP routes, LLM providers, MCP servers, and agents — giving you a unified way to enforce access rules.

For a general overview of how policies are structured, see Policy sections.

How authorization works

Agentgateway uses the authorization field inside an AgentgatewayPolicy to evaluate whether an incoming request should be allowed or rejected. Authorization rules are expressed as Common Expression Language (CEL) expressions, which let you match on request headers, JWT claims, source IP addresses, MCP tool names, and more.

The following table lists the authorization fields in an AgentgatewayPolicy:

You can also configure backend authorization inline on an AgentgatewayBackend:

Backend authorization runs after the destination backend or AI provider is selected. Traffic authorization runs earlier, during traffic policy processing. Both inline fields use the same action and policy.matchExpressions structure as spec.backend.authorization. For an example, see Authorize requests to a selected backend. For inline and attached policy precedence, see Inline AI and authorization policies on a backend.

Each authorization block contains a single action and a policy with matchExpressions. Because an authorization block takes only one action, a configuration that needs more than one action must be split across multiple AgentgatewayPolicy resources. For an example, see Combine Allow with Require.

Authorization actions

Evaluation order

When AgentgatewayPolicy resources are applied to a Gateway, their authorization rules are combined and evaluated as follows:

1. Deny rules are evaluated first. If any Deny expression matches, the request is denied, even if an Allow rule also matches.
2. Require rules are evaluated next. If any Require expression is false, the request is denied.
3. Allow rules are evaluated last. If at least one Allow rule is configured, then at least one Allow expression must match, or the request is denied.

This makes Allow and Require the recommended combination for safe, readable policies.

Note that authorization runs only after authentication succeeds. A request with a missing, malformed, or unverifiable JWT fails JWT authentication and returns a 401 before any authorization expression is evaluated. Authorization denials return a 403.

Setup and test authorization

This section walks you through an end-to-end authorization setup that allows requests from one user and denies requests from another.

Before you begin

1. Follow the Get started guide to install agentgateway.

2. Follow the Sample app guide to create a gateway proxy with an HTTP listener and deploy the httpbin sample app.

3. Get the external address of the gateway and save it in an environment variable.

   Cloud Provider LoadBalancerPort-forward for local testing

   Tip

   Kind cluster? Kind does not support LoadBalancer services by default. To use this option with a Kind cluster, install and run cloud-provider-kind.

   export INGRESS_GW_ADDRESS=$(kubectl get svc -n agentgateway-system agentgateway-proxy -o jsonpath="{.status.loadBalancer.ingress[0]['hostname','ip']}")
   echo $INGRESS_GW_ADDRESS  

   kubectl port-forward deployment/agentgateway-proxy -n agentgateway-system 8080:80

1. Apply the authorization policy

Apply an AgentgatewayPolicy that validates JWTs and allows only requests from the user alice.

kubectl apply -f- <<EOF
apiVersion: agentgateway.dev/v1alpha1
kind: AgentgatewayPolicy
metadata:
  name: authz-guide
  namespace: agentgateway-system
spec:
  targetRefs:
  - group: gateway.networking.k8s.io
    kind: Gateway
    name: agentgateway-proxy
  traffic:
    jwtAuthentication:
      mode: Strict
      providers:
        - issuer: solo.io
          jwks:
            inline: '{"keys":[{"use":"sig","kty":"RSA","kid":"5891645032159894383","n":"5Zb1l_vtAp7DhKPNbY5qLzHIxDEIm3lpFYhBTiZyGBcnre8Y8RtNAnHpVPKdWohqhbihbVdb6U7m1E0VhLq7CS7k2Ng1LcQtVN3ekaNyk09NHuhl9LCgqXT4pATt6fYTKtZ__tEw4XKt3QqVcw7hV0YaNVC5xXGYVBh5_2-K5aW9u2LQ7FSax0jPhWdoUB3KbOQfWNOA3RwOqYn4gmc9wVToVLv6bXCVhIYWKnAVcX89C00eM7uBHENvOydD14-ZnLb4pzz2VGbU6U65odpw_i4r_mWXvoUgwogXAXp80TsYwMzLHcFo4GVDNkaH0hjuLJCeISPfYtbUJK6fFaZGBw","e":"AQAB"}]}'
    authorization:
      action: Allow
      policy:
        matchExpressions:
          - "jwt.sub == 'alice'"
EOF

For a full list of available CEL variables you can use in expressions, see the CEL reference.

2. Save the JWT tokens

Save JWT tokens for the users Alice and Bob. Both tokens are signed by the key in the JWKS that you applied in the previous step, so both pass authentication. Only Alice’s token satisfies the authorization rule.

You can optionally create other JWT tokens by using the JWT generator tool. Note that to use JWTs with agentgateway proxies, make sure that the JWTs return Key ID (kid) and expiration date (exp) values in the JWT header.

1. Save the JWT token for Alice, whose sub claim is alice.

   export ALICE_JWT="eyJhbGciOiJSUzI1NiIsImtpZCI6IjU4OTE2NDUwMzIxNTk4OTQzODMiLCJ0eXAiOiJKV1QifQ.eyJpc3MiOiJzb2xvLmlvIiwic3ViIjoiYWxpY2UiLCJleHAiOjIwNzM2NzA0ODIsIm5iZiI6MTc2NjA4NjQ4MiwiaWF0IjoxNzY2MDg2NDgyfQ.C-KYZsfWwlwRw4cKHXWmjN5bwWD80P0CVYP6-mT5sX6BH3AR1xNrOApPF9X0plwVD4_AsWzVo435j1AmgBzPwIjhHPKtxXycaKEwSEHYFesyi-XCEJtaQZZVcjOJOs-12L2ZJeM_csk9EqKKSx0oj3jj6BciqBnLn6_hK9sEtoGenEVWEdOpkjRQBxk1m-rVZNY2IvxXMuj9C7jGXv_Sn3cU5w6arXWUsdoQtYTl5tmuF15nkD3DnQfLjDyz59FTKXUR_QkhXV81amejrDSTroJ42_RLC9ABXqdMORCe-Hus-f1utLURfAYGvmnEVeYJO8BFhedTR6lFLnVS0u2Fpw"

2. Save the JWT token for Bob, whose sub claim is bob.

   export BOB_JWT="eyJhbGciOiJSUzI1NiIsImtpZCI6IjU4OTE2NDUwMzIxNTk4OTQzODMiLCJ0eXAiOiJKV1QifQ.eyJpc3MiOiJzb2xvLmlvIiwic3ViIjoiYm9iIiwiZXhwIjoyMDczNjcwNDgyLCJuYmYiOjE3NjYwODY0ODIsImlhdCI6MTc2NjA4NjQ4Mn0.ZHAw7nbANhnYvBBknN9_ORCQZ934Vv_vAelx8odC3bsC5Yesif7ZSsnEp9zFjGG6wBvvV3LrtuBuWx9mTYUZS6rwWUKsvDXyheZXYRmXndOqpY0gcJJaulGGqXncQDkmqDA7ZeJLG1s0a6shMXRs6BbV370mYpu8-1dZdtikyVL3pC27QNei35JhfqdYuMw1fMptTVzypx437l9j2htxqtIVgdWUc1iKD9kNKpkJ5O6SNbi6xm267jZ3V_Ns75p_UjLq7krQIUl1W0mB0ywzosFkrRcyXsBsljXec468hgHEARW2lec8FEe-i6uqRuVkFD-AeXMfPhXzqdwysjG_og"

3. Verify the policy

1. Send a request without a JWT. The request fails JWT authentication before authorization runs, so you get back a 401 Unauthorized response.

   Cloud Provider LoadBalancerPort-forward for local testing

   curl -i http://$INGRESS_GW_ADDRESS:80/headers -H "host: www.example.com"

   curl -i localhost:8080/headers -H "host: www.example.com"

   Example output:

   HTTP/1.1 401 Unauthorized

2. Send a request with Bob’s JWT. The token is valid, so authentication succeeds, but the sub claim does not match the Allow expression. You get back a 403 Forbidden response.

   Cloud Provider LoadBalancerPort-forward for local testing

   curl -i http://$INGRESS_GW_ADDRESS:80/headers -H "host: www.example.com" \
    -H "Authorization: Bearer $BOB_JWT"

   curl -i localhost:8080/headers -H "host: www.example.com" \
    -H "Authorization: Bearer $BOB_JWT"

   Example output:

   HTTP/1.1 403 Forbidden

3. Send a request with Alice’s JWT. The token is valid and the sub claim matches the Allow expression, so the request succeeds.

   Cloud Provider LoadBalancerPort-forward for local testing

   curl -i http://$INGRESS_GW_ADDRESS:80/headers -H "host: www.example.com" \
    -H "Authorization: Bearer $ALICE_JWT"

   curl -i localhost:8080/headers -H "host: www.example.com" \
    -H "Authorization: Bearer $ALICE_JWT"

   Example output:

   HTTP/1.1 200 OK

More examples

Authorize requests to a selected backend

Complete Setup and test authorization first, and keep the Gateway’s JWT and traffic authorization policy in place. The following backend policy allows only GET requests to the httpbin Service. The Gateway’s traffic policy still requires Alice’s JWT. After agentgateway selects httpbin as the destination, the backend policy also checks the request method.

1. Create a policy in the same namespace as the httpbin Service that it targets.

   kubectl apply -f- <<EOF
   apiVersion: agentgateway.dev/v1alpha1
   kind: AgentgatewayPolicy
   metadata:
     name: httpbin-backend-authz
     namespace: httpbin
   spec:
     targetRefs:
     - group: ""
       kind: Service
       name: httpbin
     backend:
       authorization:
         action: Allow
         policy:
           matchExpressions:
           - "request.method == 'GET'"
   EOF

   Field	Description
   spec.targetRefs	Targets the httpbin Service in the policy’s namespace. The policy applies when a route selects that Service as its backend.
   spec.backend.authorization.action	Allow requires at least one expression to match.
   spec.backend.authorization.policy.matchExpressions	Allows only requests whose HTTP method is GET.

2. Send a GET and a POST request with Alice’s JWT. The GET request satisfies both policies and returns 200. The POST request passes the Gateway’s JWT and traffic authorization checks, but the backend policy denies it with 403.