Gateways

Agents rarely talk to one service with one set of credentials. They call your own APIs and tools, a remote Linear MCP server, a customer's HubSpot, and sometimes a different environment per tenant. A gateway sits in the middle of that traffic, so agents connect to the gateway and the gateway reaches everything behind it. The gateway can front APIs, MCP servers, or both, and Descope protects each of them the same way, as a Resource.

Descope is gateway agnostic. It can be the identity provider for any gateway you already run, and it also offers the Descope Agent Gateway for you to deploy yourself.

When to Use a Gateway

Whether to add a gateway is mostly an architecture decision. Descope's tokens and policies already tell users, tenants, and agents apart without one, so the real question is where you want routing, token exchange, and request-level controls to live. The answer also depends on whose agents are connecting. An external gateway exposes your APIs and MCP servers to your customers' agents, and an internal gateway carries the agents your own employees run. Use Cases covers how identity works on each side.

A gateway fits when one or more of these apply:

• You want a separate endpoint per customer: In an external use case, a gateway lets you give each customer their own URL without deploying anything new behind it. Every customer's gateway routes to the same MCP servers and APIs you already run. Adding a customer then means creating a gateway, not another server. One Gateway or One per Customer compares this with one shared URL.
• You want one endpoint for all of your agents' traffic: In an internal use case, every agent connects to a single URL, and the routes and tools behind it come back from that one endpoint. Each MCP client is configured once, instead of once for every server it uses.
• Your MCP servers already exist, and you don't want to change them: A gateway adds routing and authorization in front of servers you've already built, so you don't have to build Descope token validation, scopes, and policy checks into each one.
• You want token exchange in one layer: Without a gateway, each server that calls a downstream API runs its own token exchange and holds the client credentials to do it, and each server that calls a third-party service fetches its own Connection tokens. A gateway does both for every route, in one layer in front of all your Resources. How the Gateway Gets Downstream Credentials shows the request.
• You need features that live in the request path: Rate limits, per-customer quotas, and similar controls are gateway features, available in the Descope Agent Gateway or in the gateway you bring. Per-Customer Limits and Plan Tiers and Auditing Every Call cover how Descope tokens feed them.

When You Don't Need One

A gateway adds a hop, so skip it when none of the reasons above apply. You don't need a gateway to keep customers apart. One MCP server can serve every customer, filtering tools by the tenant on each token and making its own token exchanges. The Multi-Tenant MCP Server example builds this end to end.

If you're protecting a single API or MCP server, or a few that you're happy to have validate Descope tokens themselves, start with Resources, or for MCP, the MCP server guide.

For your employees' agents, XAA can replace an internal gateway when every tool they use supports it. The section on Gateway or XAA covers how to choose between them.

How Descope Fits

Descope can be the identity provider for a gateway you already run, or it can be the gateway.

Gateway Architecture

Every gateway Descope works with follows the same layout, whether you run your own or the Descope Agent Gateway, and whether it's internal or external.

Each gateway has one URL that agents connect to, and Descope represents it as a single Resource that agents authenticate to. Each agent has one session with the gateway, and its access token is minted only for the gateway, never for a downstream service.

Behind the URL, the gateway reaches each downstream API or MCP server, which the Descope Agent Gateway calls a route. Each one needs one of two credentials:

• Another Descope token, with a different audience: When the service is a Resource, the gateway exchanges the agent's token for a token minted for that service's audience
• A Connection token: When the service is a third-party API or doesn't validate Descope tokens, the gateway fetches the OAuth token or API key from the Connections vault

Either way, the agent never holds a downstream credential, and a token taken from one hop is rejected everywhere else.

How the Gateway Gets Downstream Credentials

For each route, the gateway trades the access token the agent sent it for the token the downstream service needs. Which Descope endpoint it calls depends on the route:

• Resource routes: The gateway calls the Descope token endpoint with a token exchange, authenticating with its own client credentials and setting resource to the route's Resource URL. Descope returns a JWT for that audience that still identifies the same user and tenant.
• Connection routes: The gateway calls the Connection token endpoints with the agent's access token. Descope returns the vaulted OAuth token or API key that the token's user or tenant has stored.

Because each downstream Resource accepts only tokens for its own aud, an agent also can't skip the gateway by calling your APIs directly with its gateway token.

For client setup and when passing the agent's token through is fine, see Downstream credential access. See Policies on Both Sides of the Gateway for how the two checks work.

Using Your Own Gateway

Any gateway that validates JWTs against a JWKS can use Descope as its identity provider. For the settings to point it at, and setup notes for specific gateways, see Gateway Integrations.

Internal and External Gateways

The layout above is the same on both sides. What changes is who signs in, how you split access between them, and how many gateways you run:

For how identity works on each side beyond the gateway, see Use Cases.

Internal Gateways

An internal gateway carries the agents your own employees run. Use one gateway. Every agent connects to a single URL, the routes and tools behind it come back from that one endpoint, and each MCP client is configured once instead of once for every server it uses.

Role and Group-Based Policies

Employees sign in through your workforce IdP over SSO, so access usually follows the groups they're already in. Map your IdP groups to Descope roles, then use user.roles in policy conditions to decide which routes and scopes each group gets. For example, engineering can get write access to GitHub while support only gets read access to the billing API. Add client.tags to limit which agents can use a route at all.

Every agent's traffic goes through the gateway, so these policies are the one place you change access. You revoke an agent, or tighten what a group can do, there instead of in each MCP client's config. For example rules, see Recommended Policy Patterns.

Employee Connections

When an agent calls a third-party tool, the gateway fetches the employee's own stored credential from Connections with the agent's token, so the agent never holds a third-party token or API key.

Employees connect their accounts once, using one of the methods in Storing Connection Tokens. For a tool your whole company shares one account on, store a tenant-level token instead. See Token Scope Models, for how user and tenant tokens differ.

External Gateways

An external gateway exposes your APIs and MCP servers to your customers' agents. Each customer is a tenant in Descope, and everything in this section keys on that tenant: which gateway URL the customer uses, what their policies allow, whose Connections the gateway uses, and what limits apply.

One Gateway or One per Customer

You can give every customer one shared gateway, or give each customer a gateway of their own. Both layouts are common, and the choice is up to you. It mostly comes down to which URL you want each customer to use. The architecture inside each gateway is the same either way.

Each customer is a tenant in both layouts, so a gateway isn't a stand-in for a tenant. It's closer to a login URL. One shared gateway is like one app that every tenant signs in to, and a gateway per customer is like giving each tenant a subdomain of its own. If you already give each customer their own subdomain or environment, a gateway per customer follows the same pattern.

With one gateway for everyone, the gateway tells customers apart by the tenant on each token: the dct claim for a user, or the tenant a client credentials client is associated with. One URL is also what Claude Connectors and ChatGPT plugins for B2B require, since they expect a single URL for all of your customers.

To give each customer their own endpoint instead, create a separate gateway for each customer with that base URL. Each gateway has its own gateway Resource, so a token minted for customer A's gateway is rejected at customer B's gateway. The gateways can all route to the same MCP servers and APIs, reusing the same Resource so a shared server is defined once, which is what makes adding a customer quick.

The tradeoff is that every new customer means another gateway to create and keep configured, and the layout doesn't work with channels that need one URL for every customer. For more on tenant isolation in each layout, see One URL, Many Tenants and Shared or Per-Customer MCP Servers.

Per-Tenant Policies

Whichever layout you pick, policies keep customers apart on both sides of the gateway. Conditions such as user.tenantIds decide which scopes a customer's agents can get on the gateway, and which targets the gateway may get credentials for on that customer's behalf. Give each tool or endpoint its own scope, so a customer's policy grants only what they paid for.

Within each tenant, the customer's own roles and groups can drive access too. Map that customer's SSO groups to roles and combine those roles with the tenant in policy conditions. A customer's admins can then get write scopes while the rest of their users get read scopes, and one customer's agents can't request another customer's write scopes.

For example rules, such as partner agents limited to a shared docs server or write access only on staging, see Recommended Policy Patterns. For how the two checks fit together, see Policies on Both Sides of the Gateway.

Per-Tenant Connections

A gateway often calls third-party services on a customer's behalf, like reading that customer's HubSpot. Those credentials usually belong to the customer, so give each customer their own Connection when they bring their own OAuth app, API key, or host. When the gateway fetches a Connection credential with the agent's token, Descope uses the Connection that matches the tenant on the token, the dct claim. One gateway can then keep each customer's credentials, endpoints, and scope mappings separate.

See Per-Tenant Connections for how to create them, and Storing Connection Tokens for how users and tenants connect their accounts.

Per-Customer Limits and Plan Tiers

External gateways usually also enforce limits per customer, such as request quotas, or which tools and endpoints a free plan can reach compared with an enterprise plan. Descope's token service doesn't rate-limit gateway traffic. The gateway does, whether that's the Descope Agent Gateway or your own, and the Descope token gives it what it needs to key those limits: the dct claim identifies the customer's tenant, and the scope claim reflects what that customer's policies allow. The gateway can apply a quota per tenant, or reject a call the customer's plan doesn't include.

Tie plan tiers to policies rather than to gateway config where you can. When a customer upgrades, you change which scopes their policy grants, and the gateway picks up the new scopes from the next token without a redeploy.

Protecting Your Agentic Infrastructure (One Step at a Time)

Descope works inside your infrastructure, not in front of all of it. You don't have to put every backend behind Descope on day one. You can protect your stack a piece at a time, and each piece you add gets its own policy.

Two things stay the same at every stage. The client (agent) always gets its token directly from Descope, minted for the gateway's audience, and the gateway always validates that token before doing anything else. What changes is how much of the path behind the gateway Descope handles. Most teams move through the same three stages:

1Protect the gateway2Add Connections3Protect your APIs as Resources

The client gets its token straight from Descope, and the gateway validates it. A policy decides which clients and users may reach the gateway at all. Everything behind the gateway still runs on your own STS, secret store, or existing API auth.

You can start with just the gateway: Descope handles login, consent, CIMD/DCR, and the client-to-gateway policy, while your existing auth keeps running behind it.

Adding Connections moves downstream credentials, per user or per tenant, into Descope, so the gateway fetches them from the Connection token endpoints instead of a token store you run.

Moving internal APIs onto Resources adds a token exchange call, with the API's URL as resource, and each API validates a Descope JWT for its own audience.

We recommend starting with the first two together, then moving services onto Resources as you get to them. The gateway already sends the agent's token to Descope for every Connection route, so a Resource route is one more call of the same kind, to the token endpoint instead.

Policies on Both Sides of the Gateway

A gateway sits between many clients and many downstream services, and those two sides need different rules. Descope checks them separately, the same way it checks a policy on every hop in any chain of calls:

• Client to gateway: Every agent has one session with the gateway, so a single policy for the gateway's Resource decides which clients and users may reach it, and with which scopes. One policy covers both user-delegated access (authorization code with consent) and machine-to-machine access (client credentials).
• Gateway to each route: Each route's Resource or Connection has its own Delegated access (token exchange) policy, checked every time the gateway asks Descope for that route's credential. The same gateway can be allowed to read from your billing API but not write to it, or to use one customer's HubSpot Connection but not another's.

Auditing Every Call

Once every downstream call goes through the gateway, you get one place to decide what an agent may do, and one record of what it did. On top of the two policy checks, the gateway can require a different scope per tool or endpoint, such as a read scope for one and a write scope for another, since the inbound token's scope claim carries only what the user consented to and policy allowed.

When a token exchange is denied, the call never reaches the downstream service, and Descope writes a Warning audit event with the client, target, requested scopes, and evaluation outcome. The Agentic Activity Dashboard rolls those up by MCP server and by Connection, so you can see which agents keep asking for more than they're allowed.

Because the agent's token is only valid at the gateway, each downstream hop is its own grant: user, then client, then gateway, then the downstream service. That is what makes the trail readable when you need to answer who did what on whose behalf.

Descope covers identity, policy, and the token trail. Inspecting request payloads, detecting prompt injection, and similar content checks come from the gateway product you run. Protecting Third-Party APIs Internally covers when those controls are the reason to add a gateway, with or without XAA behind it.

Next Steps

1. Set up the gateway. For the Descope Agent Gateway, follow Setting Up a Gateway, which creates the gateway's Resource and Client for you. If you run your own gateway, create an MCP Server Resource for it, or an API Resource if agents call REST APIs through it, plus a Client the gateway uses for exchanges.
2. Write Policies for User access (user consent) and Delegated access (token exchange).
3. Create Connections for third-party services, and decide how users connect their accounts, for example through the Admin Portal.
4. Implement the exchange in your gateway or tool handlers with Downstream credential access or the MCP SDKs.

For how this looks for an internal gateway compared with one you expose to customers, see Use Cases, and for MCP specifics, MCP Gateways.