What are API Gateway Policies?

Your API gateway sits in front of all your upstream services. As an incoming request’s first point of contact, the API gateway dictates whether and how a request should be forwarded to an upstream service. How it makes that determination depends on API gateway policies.

In this article, we’re going to look at API gateway policies commonly used in four specific areas: authentication, authorization, security, and traffic.

What is an API Gateway Policy?

An API gateway policy is a rule that an API gateway enforces when processing incoming requests. API gateways are built to enforce these policies automatically and consistently.

Consider a restaurant with the posted sign: “No shoes, no shirt… no service.” That restaurant has a policy analogous to an API gateway policy requiring all incoming requests to have a certain shape if they are to be permitted.

Consider a bouncer standing outside a nightclub, checking the identities of lined-up partygoers against his list of guest names. Verifying identities and permitting (or denying) access is precisely the same function as an API gateway configured with policies for authentication and authorization.

API Authentication vs.  API Authorization

Before proceeding, it’s important to clarify the distinction between authentication and authorization. Authentication is the verification that somebody is who they say they are. The most common way to perform authentication is through a basic login with a username and password.

Meanwhile, authorization is the determination of what resources somebody is allowed to access. That somebody presents a token or key, which they obtained through authentication or some other means. Authorization is not concerned with how the requester got their token.

In traditional web user flows, the authentication step is immediately followed by the authorization step, which is why the two are so often conflated or confused. Because of their proximity, we will consider both authentication and authorization policies together.

Authentication and Authorization Policies

Beyond the vanilla login steps of entering a username and password, other means of facilitating authentication include OAuth2.0, OpenID Connect, mutual TLS, and the use of tokens. Tokens play an important role in authentication and authorization. The holder of a token—such as an OAuth authorization token or a JSON Web Token (JWT)—presents that token to an API gateway. Possession of a valid secret token is considered proof enough of one’s identity, making it a vehicle for authentication. Often, that token serves also as a vehicle for authorization.

An API gateway enforces authentication policies and subsequent authorization policies before forwarding requests to their final destination.

OAuth 2.0 Authentication

OAuth 2.0 is an authorization protocol but is often used to facilitate authentication as well. If you have ever seen a website with a “Login with Google” or “Login with Facebook” button, you’re seeing OAuth 2.0 in action. That website (a.k.a. “client application”) has outsourced its authentication strategy to a third party (for example, to Google). They are essentially saying, “If Google vouches for you that you are so-and-so, then I’ll accept that you are so-and-so.” The typical OAuth flow looks like this:

  1. The user clicks on the “Login with Google” button, then is redirected to the third-party identity provider’s site.
  2. The user logs in with that third-party identity provider.
  3. The user is redirected back to the original website, holding a token from the identity provider.
  4. The client application validates the token with the identity provider.
  5. The identity provider authenticates the token as valid, vouching for the user’s claimed identity.

The OAuth 2.0 Authentication plugin enables Kong’s API Gateway to serve as an identity provider. Assuming the user is logged in at that identity provider service behind API Gateway, then the API Gateway grants a token (via the plugin) for the user to bring back to the requesting client application. The API Gateway handles authorization requests and—with the authentication policy in place—knows whether to grant, inspect, or refresh tokens.

OpenID Connect

OpenID Connect is a simple layer built on top of the OAuth 2.0 protocol, used to facilitate authentication for all types of clients on all kinds of platforms. We mentioned above that the user needs to be authenticated with the identity provider for an authorization token to be granted. Using OpenID Connect, in conjunction with OAuth 2.0, is one way of facilitating that authentication.

The OpenID Connect plugin enables your Kong API Gateway to function as an OpenID Connect Relying Party. This means it can support various ways that a user authenticates himself, including username/password credentials, JWT, or an opaque token.

Coupled together, OpenID Connect facilitates the authentication policy, while OAuth 2.0 facilitates the authorization policy.

Mutual TLS Authentication

In mutual TLS authentication, an API gateway uses client-supplied certificates and trusted certificate authorities to facilitate authentication. When the mutual TLS authentication plugin is used with Kong API Gateway, the API Gateway negotiates a TLS handshake with the client, inspects the certificate presented with the request, and validates it against a pre-configured list of trusted certificate authorities. If the certificate is valid, then the API Gateway writes information about the requester to the upstream headers and forwards the request to the upstream service.

JSON Web Tokens (JWT)

A JSON Web Token (JWT) is a string that contains a hashed data payload. It is typically not encrypted, such that the data payload can be easily decoded and read. However, the JWT is signed with a secret key by a trusted party to prevent spoofing. The validating party needs access to the same secret key used by the signing party. It’s very common for the signing party and the validating party to be one and the same.

A JWT is attached to a request in the Authorization header, complying with the standard Bearer Auth scheme. A token’s payload can contain claims about the token holder’s identity as well as claims about what resources that token holder can access. As long as the token was signed by a trusted party, then those claims can be considered valid, and both authentication and authorization are achieved.

Kong’s JWT plugin facilitates the validation of JWTs and the forwarding (or denying) of requests.

API Key Authentication

There are use cases when a user’s identity is of no consequence. What matters is not who the holder of the token is, but rather what resources that holder is permitted to access. One example of this might be the API Key.

Requests may have an API key attached—perhaps in a header called x-api-key or in a query parameter or body data. The Key Authentication plugin finds the request’s API key and verifies it against a list of valid keys. Based on that verification, the API gateway knows whether to block a request or forward it to the upstream service. The plugin also writes identifying data to the upstream headers so that the upstream service can determine even more granularly what resources the requester can access.

Security Policies

Your API gateway functions like the security guard standing in front of all your upstream services, enforcing rules or making assessments before allowing an individual to pass, regardless of that individual’s identity. Security policies are separate from authentication policies, but still important for protecting upstream services from malicious access.

IP Restriction

IP restriction is one type of security policy, restricting access to a service based on the source IP of that request. Kong’s IP Restriction plugin manages access to a service or route, enabling the permitting or denying of requests based on single IPs, multiple IPs, or IP ranges with CIDR notation.

Bot Detection and Threat Analyses

The Bot Detection plugin guards your services by denying access to common bots. It comes already built with basic rules to handle oft-seen offenders. Several other plugins (For example, Cleafy and Approov API Threat Protection) can also provide automated threat analysis and protection.

OPA Integration

Kong’s API Gateway also integrates with its OPA plugin, which runs inbound requests through an Open Policy Agent to evaluate against authorization policies established there. The plugin ensures that only those requests that pass authorization get processed.

For example, you might run an OPA server that is configured to enforce the policy “Accept requests that contain the header gatekeeper equal to the value keymaster. Deny all other requests.” All requests that come through Kong’s API Gateway get routed to that OPA server via the plugin. Every request is checked for the required header value, and the plugin essentially gets an “accepted” or “rejected” response from that OPA server. Based on that response, the API Gateway knows how to handle the request.

Traffic Policies

Traffic policies enforce rules that ensure that the load placed on upstream services is within healthy boundaries. The most common types of traffic policies center around rate limiting, circuit breakers, and request throttling.

Rate Limiting

Rate limiting is commonly used to defend against DDoS attacks. In a rate limiting policy, you establish a window of time for counting requests (perhaps every 30 seconds) and a threshold for what qualifies as “too many requests” (maybe 10 requests). An API Gateway then rejects subsequent requests if they exceed the given threshold within the given window of time. This occurs until the incoming request rate falls below the threshold.

The policy can rate-limit excessive incoming requests indiscriminately, regardless of who is sending those requests, or it can apply rate limits by client IP address or by an authenticated user. (For example, Alice can send up to 10 requests every 30 seconds, and Bob can send up to 10 requests every 30 seconds.)

The Rate Limiting plugin for Kong’s API Gateway allows for easy configuration of rate limiting traffic policies to protect your upstream services.

Circuit Breakers

An API Gateway can function as a load balancer, taking incoming requests for a service and distributing those requests across multiple replicas of that service. To ensure stable and successful request handling, a load balancer might apply passive health checks, also known as circuit breakers, as a traffic policy.

For a circuit breaker, the load balancer checks the request as it makes its way to one replica of the upstream service. If that upstream target is not responsive, the load balancer marks that replica as “out of service.” For all subsequent requests, the load balancer skips this unhealthy target, only distributing requests to the remaining healthy targets.

Request Throttling

When some sort of traffic policy is violated (like a rate limit), an API gateway can carry out other measures besides simply denying requests altogether. One such alternative is request throttling. Request throttling works similarly to rate limiting, except that requests exceeding the threshold are not denied right out; instead, they are queued for later processing. This type of policy slows down incoming requests to the desired rate.

The difference between rate limiting and request throttling can seem subtle. Perhaps the nuances can be best clarified by way of illustration. Imagine an intersection that regularly experiences too much traffic, resulting in frequent collisions. One policy measure (rate limiting) would place a barrier up the street, with a sign that says, “Road closed until 4:00 PM.” With no way to get through the intersection until the road reopens, cars would be forced to turn around. Another policy measure (request throttling) would install speed bumps in the miles of road leading up to the dangerous intersection. Incoming cars, slowed down by the speed bumps, would arrive at the intersection at a slower rate, in hopes of keeping the flow of traffic to the intersection at a reasonable rate.


In this article, we’ve covered API gateway policies concerning authentication and authorization, security, and traffic. With the API gateway positioned as the front office, regulating access to upstream services, the API gateway governs the handling of incoming requests. How to handle those requests—allow them, deny them, limit them, reroute them, or transform them—all depends on the setup and configuration of these policies.