OCI API Gateway: Routing, Auth, and Rate Limits

Most teams discover they need an API gateway the hard way. A function or a service gets exposed directly, a partner integration goes live, and suddenly questions arrive that the application itself was never meant to answer. Who is allowed to call this? How many calls per second can it absorb? Where do we see what came in and what went out? Who rotated the certificate? An API gateway exists to answer those questions in one place, consistently, for every API behind it, so that individual services do not each grow their own half finished copy of authentication, throttling, and logging.

OCI API Gateway is the managed answer to that problem on Oracle Cloud Infrastructure. It is a regional, fully managed service that you place inside your own VCN, point at your backends, and configure with declarative policies. There are no instances to size, no patches to apply, and no gateway cluster to keep alive across availability domains, because the platform handles all of that. This article is the practitioner companion to our pillar guide to application development and serverless on OCI, and it goes deep on the gateway itself: how deployments and routes work, how authentication and rate limiting are enforced, what the observability story looks like, and what separates a demo gateway from a production grade one.

What OCI API Gateway actually is

The service has a deliberately small resource model. You create a gateway, which is a regional endpoint living in a subnet of your VCN. The gateway can be public, with an internet reachable endpoint, or private, reachable only from inside the VCN and anything peered or connected to it. On top of a gateway you create one or more deployments, and each deployment is a versioned specification that contains a path prefix, a set of routes, and the policies that apply to them. A single gateway can host many deployments, which is how teams typically separate APIs by product, by audience, or by lifecycle stage.

Because the gateway lives in your VCN, it participates in your network security model like any other resource. Network security groups and security lists control who can reach it, route tables decide what it can reach, and the same FastConnect or VPN connectivity that serves the rest of your estate serves the gateway too. That placement is one of the most underrated aspects of the service: the gateway is not a bolt on edge appliance outside your perimeter, it is a first class citizen of the network design you already govern through your landing zone. Our OCI networking practice treats gateway subnets as a standard part of the hub and spoke layout for exactly this reason.

Deployments, routes, and backends

Inside a deployment, traffic is matched by routes. A route pairs a path pattern with the HTTP methods it accepts and the backend that serves it. Path matching supports parameters and wildcards, so a single deployment can express a clean REST surface: a GET on a collection path, a POST on the same path, a GET with a path parameter for a single item, and so on. Method level matching matters more than it first appears, because it lets you apply different policies to reads and writes on the same path, such as a generous rate limit for GET and a strict one for POST.

Three backend types

Each route points at one of three backend types. The first is an OCI Functions backend, which invokes a serverless function directly and makes the gateway and functions pairing the default pattern for serverless APIs on OCI. We cover the function side of that pairing, including cold starts, concurrency, and packaging, in our guide to OCI Functions. The second is an HTTP backend, which proxies to any HTTP endpoint the gateway can reach: a load balancer in front of services on OKE, a service on a compute instance, or even an external API. Teams running containerized estates usually put the gateway in front of an internal load balancer, a pattern that fits naturally with the service designs in our article on microservices patterns on OKE. The third is a stock response backend, which returns a fixed status, headers, and body without calling anything. Stock responses sound trivial until you need a health endpoint, a mock for a consumer who is building against an API that does not exist yet, or a maintenance response you can switch on during a cutover.

Authentication and authorization

Authentication is where a gateway earns its place, because doing it once at the edge is dramatically better than doing it inconsistently in every service. OCI API Gateway gives you three mechanisms that cover the large majority of real designs.

JWT validation against any OIDC issuer

The most common pattern is token validation. The gateway can validate JSON Web Tokens issued by OCI IAM identity domains, the successor to IDCS, or by any standards compliant OIDC issuer such as Auth0, Entra ID, Okta, or Keycloak. You configure the issuer, the audiences you accept, and either static public keys or a remote JWKS URI that the gateway uses to fetch and cache signing keys. The gateway rejects expired or malformed tokens before they ever touch your backend, and it can enforce scope and claim requirements per route, so a route that mutates data can demand a write scope while a read route accepts less. Validated claims can then be forwarded to the backend as headers, which means your services receive identity as trusted context rather than re parsing tokens themselves.

Authorizer functions for custom logic

When token validation is not enough, the gateway can call an authorizer function: an OCI Function you write that receives the incoming credentials, applies whatever logic you need, and returns an allow or deny decision along with the context to pass downstream. This is the escape hatch for API keys held in a database, legacy token formats, per tenant entitlement checks, or any scheme an off the shelf validator cannot express. The decision can be cached, so a well built authorizer adds little latency in steady state. One caution from the field: authorizer functions are production code on the critical path of every request, so they deserve the same testing, secret handling, and observability as any service. Credentials and signing material they depend on belong in a managed secret store, a discipline we walk through in our article on OCI Vault and secrets management.

mTLS for machine to machine traffic

For partner integrations and internal machine to machine traffic, the gateway supports mutual TLS. The gateway presents its certificate as usual, but it also demands a client certificate and validates it against certificate authorities you configure, optionally restricting accepted certificates by subject name. mTLS shifts authentication from something the request carries to something the connection proves, which is why regulated industries lean on it for B2B traffic. It composes with JWT validation, so a route can require both a trusted client certificate and a valid token.

Request and response transformation

Real APIs rarely match their backends perfectly, and the gateway includes transformation policies to absorb the difference. Header transformation policies can add, rename, or strip headers in both directions: inject a correlation ID on the way in, remove an internal header that should never leak on the way out, or rewrite a header a legacy backend insists on. Query parameter policies do the same for the query string. Request body validation policies let you require a body, restrict accepted content types, and reject malformed payloads at the edge, which protects backends from junk input and gives consumers fast, consistent error responses. None of this replaces a full transformation engine, and it is not meant to. The design intent is that the gateway shapes the envelope of a request while the backend owns its meaning, and teams that respect that boundary end up with policies that stay readable.

Rate limiting, usage plans, and monetization style controls

Rate limiting is the second pillar of the gateway's job. The basic mechanism is a rate limiting policy on a deployment, expressed as requests per second, applied either across all callers or per client IP. That is your blunt instrument against runaway consumers and accidental retry storms, and every public deployment should have one even if the number is generous.

The finer instrument is usage plans. A usage plan defines entitlements, such as a rate limit and a quota over a billing style window, and subscribers hold tokens that tie their requests to a plan. This turns the gateway from a traffic valve into a product surface: a free tier with a low quota, a paid tier with a higher one, a partner tier with negotiated limits. The gateway counts requests per subscriber, enforces the entitlements, and emits the data you need to see who consumed what. It is not a billing system, and you still need something to invoice against that consumption, but the enforcement and metering layer comes free with the service. For organizations heading toward API products rather than mere API endpoints, this is the feature set where governance questions begin, and our companion piece on API management strategy on OCI takes those questions further.

CORS, caching, and custom domains

Three smaller capabilities round out the request path. CORS policies let the gateway answer preflight requests and attach the right response headers for browser based consumers, configured per deployment with allowed origins, methods, and headers, so backends never need CORS code at all. Response caching integrates with an OCI Cache cluster you provide: the gateway caches eligible responses by key and serves repeats without touching the backend, which can flatten read heavy traffic dramatically. And custom domains with TLS certificates let your API live at a name you own rather than the generated gateway hostname. Certificates can come from the OCI Certificates service, which handles rotation, or be brought in from elsewhere, and private keys for imported certificates belong in Vault rather than in a wiki attachment. TLS termination at the gateway is always on, so the only question is whose name is on the certificate.

Observability: logs, metrics, and tracing

You cannot govern what you cannot see, and the gateway is well instrumented. Access logs record each request with method, path, status, latency, and caller information, flowing into OCI Logging where they can be searched, archived, or shipped onward. Execution logs record what the gateway did internally, including policy evaluation and backend errors, at a verbosity you control, and they are usually the fastest way to diagnose why a request was rejected. Metrics in OCI Monitoring cover request counts, latencies, response code classes, and backend timings, which is what your alarms should watch: a spike in 401 responses means an issuer problem, a spike in 504 responses means a backend problem. Finally, the gateway participates in distributed tracing through Application Performance Monitoring, so a slow request can be followed from the edge through the function or service that served it. Wire all four up on day one; retrofitting observability during an incident is the most expensive way to learn this lesson.

Networking patterns: private APIs and hybrid exposure

The choice between a public and a private gateway endpoint shapes the whole design. A public gateway serves internet consumers and is the obvious choice for partner and customer facing APIs. A private gateway has no internet endpoint at all, which makes it ideal for internal platform APIs: services across your VCNs consume them via peering, and on premises systems reach them across FastConnect or VPN. That second pattern, private APIs over FastConnect, is the quiet workhorse of hybrid estates, because it gives on premises applications a governed, authenticated, rate limited door into cloud services without anything touching the public internet. The reverse also works: a gateway can front services that still live on premises, presenting them to cloud consumers through one consistent surface while migration proceeds behind it. Getting the subnets, security rules, and DNS right for these patterns is standard landing zone work, and it is a core part of what our app modernization engagements put in place before the first API goes live.

Policies at a glance

Because the gateway is configured declaratively, it helps to keep a mental map of which policy controls what and where it attaches.

Pricing and limits

The pricing model is refreshingly simple: you pay per million API calls processed, and the rate is low enough that the gateway is rarely a meaningful line on the bill. There is no hourly charge for the gateway itself, no minimum, and no capacity reservation, which makes the entry cost essentially zero and removes the usual temptation to share one overloaded gateway across unrelated teams to save money. Adjacent costs are the ones to watch: function invocations behind functions backends, the cache cluster if you enable response caching, log storage if you retain verbose execution logs for a long time, and outbound data transfer for large responses leaving the region.

Limits deserve a glance before you commit to a design. Gateways per region, deployments per gateway, routes per deployment, request and response size caps, and header count limits are all documented and mostly generous, but two matter in practice: the payload size cap means the gateway is the wrong door for bulk file movement, which belongs on Object Storage with pre authenticated requests, and the backend timeout ceiling means long running operations need an asynchronous pattern with polling or events rather than a single heroic request.

Gateway or full API management suite?

A fair question from teams arriving with other platforms in mind is whether OCI API Gateway is an API management suite. It is not, and it does not pretend to be. It is the runtime enforcement layer: routing, authentication, throttling, transformation, and telemetry, executed at low cost and with no infrastructure to run. What a full suite adds around that runtime is the product layer: a developer portal where consumers discover APIs and sign themselves up, lifecycle workflows with approvals and deprecation policies, deep analytics on consumer behavior, and monetization with invoicing. On OCI, some of that gap is covered by usage plans and the broader platform, and some is covered by process and tooling you assemble: API specifications in source control, deployments promoted through pipelines, a catalog your consumers can actually find. Deciding which gaps matter for your organization, and whether to fill them with process, with additional products, or not at all, is precisely the subject of our API management strategy article.

A path to a production grade gateway

Pulling the threads together, here is the sequence we follow when we stand up a gateway that has to survive contact with real consumers.

From a working gateway to a governed one

A team that follows the steps above will have a gateway that is secure, observable, and cheap to run. What it will not yet have is governance: agreed standards for how APIs are named and versioned, a catalog consumers can browse, rules for who may publish a deployment and how breaking changes are communicated, and a view of API consumption that product owners rather than engineers can read. Those concerns sit above any single gateway, and they determine whether an organization ends up with an API platform or a pile of endpoints. The gateway gives you the enforcement point; strategy decides what to enforce. That is where our article on API management strategy on OCI picks up, and where the broader serverless and application story in the pillar guide places the gateway in context. If you are deciding how APIs, functions, and containers should fit together on OCI, that is a conversation worth having before the first deployment ships, not after the tenth.