Scoping API Permissions for Customer-Facing Integrations
Design your API scopes before authentication, or a valid token grants far too much access.
Scoping API permissions for customer-facing integrations is a design discipline. Each use case needs the narrowest permission surface it can work with before a token is issued. For AI agents, that choice is especially consequential because a legitimate connection can still give an unpredictable caller far too much room to move.
Why API permission scoping is a design problem, not a security afterthought
An agent can authenticate correctly and still retrieve data its user should never see. That is the central failure of over-privileged access, and it starts before the authentication layer gets involved. The product has already decided which identity the agent inherits, which tools it can call, and how much authority those tools expose. Authentication establishes who got through the door.
The familiar response of adding an API key and a rate limiter addresses a different problem. Those controls can constrain traffic without stopping a caller from exploiting legitimate, over-scoped access. Generic pre-built tool calls make this worse when they expose more of an API than a particular workflow needs.
What over-privileged access actually looks like in production
Asana’s MCP server had a tenant isolation flaw that exposed one customer’s projects and tasks to other organizations from May 1–June 4, 2025. A connection could be valid while access through it was wrong. That distinction explains why successful authentication is weak evidence that an integration is safe.
An update to the postmark-mcp npm package in September 2025 sent a hidden copy of every outgoing email to an attacker’s domain. In a proof of concept against the Supabase MCP server, attacker-crafted support tickets could make an agent dump a SQL database into a ticket reply. These were not interchangeable failures. One involved the tool supply chain, while the other used prompt injection to exploit broad tool access. Together with the Asana incident, they point to four controls that need separate scrutiny, namely credential isolation, tenant scoping, tool provenance, and least-privilege execution.
How the identity model you choose sets the blast radius before any scope is written
Before a team chooses scopes, it must decide whose authority each call uses. A bot or service identity shows that automation is at work, but logs from the application must show which person is behind it. Per-user OAuth makes actions attributable to each user, at the cost of requiring every end user to complete an OAuth flow. A shared organization token is faster to set up, but actions appear as the authorizing admin and exposure extends across the organization. Convenience has a rather large forwarding address.
Project- or workspace-scoped identity suits multi-tenant products where teams need isolated integration contexts. Salesforce queries may use per-user OAuth so each rep sees only the records they have access to, while Slack notifications use a bot token and an internal analytics warehouse uses an API key. The external API constrains the available choice. Some support only per-user OAuth, while others support only bot tokens, so the integration platform must work with the required model and make clear how the models differ in accountability and exposure.
Building the narrowest scope surface — from resource-level access to action-level scopes
With identity established, the next decision is which actions that identity may delegate. Access to a resource is too broad when the workflow only needs to read it. Slack bots, for example, request action-specific scopes such as chat:write or files:read. Reading and writing are different grants of authority. Short-lived OAuth 2.0 tokens can use narrow scopes to grant read or write access in place of broad resource-level access.
The four permission patterns form a useful ranking from greatest exposure to greatest precision. Full admin or service-account permissions are the worst case because the agent operates with elevated access. Full user permissions give it everything the user can do, which is still broader than a particular task requires. A scoped-down subset, such as calendar.readonly, is the correct default. Context-dependent permissions are more precise still because authority changes with the task or workflow, but they are the hardest to implement.
The practical rule is to start with the narrowest scope that works and widen it only for a specific use case. At the tool layer, expose an allowlist of intent-specific tools. High-impact writes should also have approval gates that check scope when the write runs, so the button does more than reassure.
Where permission enforcement must live — and why the tool boundary is not enough on its own
Two enforcement models determine who owns the authorization work. In the stronger model, the application passes a user-scoped token and Salesforce, Google, or Slack enforces that user’s access. Every end user must complete an OAuth flow. In the alternative model, an admin supplies a broad organization token and the application applies its own roles and permissions before each API call. That can work, but the team owns the enforcement logic entirely, including filters that restrict results by region and creator.
MCP authentication establishes a client’s access to an MCP server, while the tool layer must still check the permitted tenant, connection, tool, and arguments. Those checks must use trusted application or connection metadata.
Object ownership needs a further check at the service or domain layer. OWASP put Broken Object Level Authorization first in both its 2019 and 2023 API Security Top 10 lists. BOLA occurs when an endpoint authenticates a caller but does not check whether the requested object belongs to that caller. Every data access path, including REST handlers, GraphQL resolvers, background jobs, and admin tools, must re-verify ownership on every request. Non-sequential, non-guessable identifiers such as UUIDv4/v7 remove attacks based on enumerable IDs, but do not replace authorization.
Why OAuth 2.0 with short-lived tokens is the load-bearing mechanism, not a nice-to-have upgrade
For user-facing AI agents, use the Authorization Code Flow to tie delegated access to the user’s identity, tenant context, and permission scopes. A static API key does not model those distinctions. Short-lived access tokens also bound the exposure window because a compromised token expires, while a static key remains valid until it is rotated or revoked.
The token lifecycle needs protection beyond access-token expiry. OAuth 2.1 consolidates OAuth 2.0 best practices, makes PKCE mandatory for all clients, and drops the implicit grant. RFC 9700 expects PKCE and exact redirect URI matching, and strongly recommends sender-constrained tokens. With DPoP or mTLS, possession of a stolen token alone is insufficient because the client must also prove possession of a private key. Rotate refresh tokens too, since an unrotated, long-lived refresh token can become a durable attacker foothold despite narrow access scopes.
Workload identity through SPIFFE/SPIRE or cloud-provider equivalents replaces static service-to-service keys with short-lived, automatically rotated credentials for mTLS. If internal authentication still depends on a shared API key in an environment variable that has never rotated, fixing that comes ahead of almost anything else.
Tenant isolation as a scope-level concern, not just a data-layer concern
A permission scope answers what a caller may do, while tenant isolation answers whose connection and data it may use. Those are separate enforcement questions, as the Asana failure illustrates. The identifier that selects a customer connection must come from trusted server-side metadata, with model arguments and client-controlled parameters kept out of that choice. Otherwise, a request can pass authentication and still cross into the wrong customer’s connection or data.
The identity model determines where that boundary can be enforced. With a shared organization token, the application owns the isolation logic entirely. A per-user token lets the external API enforce access only if it genuinely represents the correct user. Each selected connection must therefore map explicitly to a user, workspace, organization, or service identity, with credentials kept out of model context and injected server-side. Tenant isolation failures can be operationally silent because the request returns 200, the log records success, and the evidence lies in which data crossed the boundary.
Audit logging that can reconstruct what an agent actually did with its permissions
To investigate that kind of success, logs must connect the initiating person to the authority used during execution. The identity decision made earlier now determines what is visible. Per-user tokens give the cleanest attribution, while bot identities require log enrichment to reveal the individual behind a workflow. Shared organization tokens make external actions appear to come from the authorizing admin.
A reconstructive record must show which identity or token was used, which tool calls ran, which external API requests followed, and what succeeded or failed. It also needs the workflow initiator and timing. For integration platforms, each tool call should record the principal, connection, tool, outcome, and timestamp, with exportable records. The record must also include the tenant and tool-scope context. Without them, a successful-call entry cannot establish whether the applicable boundary was respected.
An authenticated caller targeting other users’ object IDs may produce neither an authentication error nor a rate-limit event. Behavioral anomaly detection provides a signal of this behavior, making execution evidence a platform selection criterion.
Rate limiting shaped around token cost and action weight, not raw request count
One prompt can fan out into dozens of internal calls, so counting incoming requests misses the work an agent actually causes. Each downstream call has its own permission surface and cost. For content generation and agent integrations, limits should be based on token cost and what downstream actions cost. The prompt is not the unit of consequence.
Per-tenant and per-connection limits can keep a noisy tenant, broken SDK release, or retry loop from affecting other customers. High-impact writes, including publishing, sending, and deleting, warrant separate throttles from reads because their potential damage differs. A rate limiter cannot decide whether an authenticated caller should have access, so identity and scope must already be correct before it constrains the fan-out of an over-broad action.
Applying these controls when selecting or building an integration platform
Platform selection delegates part of the permission design to an execution runtime. The evaluation should therefore begin with the identity a connection represents and whether every call is bound to that principal and tenant. Credential handling is a separate test. The platform should inject provider tokens only during server-side execution, rather than let the model or agent process retrieve them. Keeping credentials out of model context is necessary, but it does not establish whose authority a call inherits.
Can one connection be refreshed, rotated, and revoked without affecting other customers? Can the application expose only intent-specific tools and require approval for high-impact writes? Tenant separation needs just as close a look, including which identifier selects the connection and how the platform keeps credentials, execution, and stored data separate.
Each tool call needs an exportable record of the principal, connection, tool, outcome, and timestamp so that permission decisions can be examined after execution. A large action catalog is not a permission model. The decisive capability is how narrowly the application can expose that catalog, bind each action to the right customer, and account for what happened afterward.



