By Nolan Sullivan, Founding Growth EngineerA shared service credential is one upstream key or token that an MCP server or agent presents for every caller. User-delegated identity gives each call a token issued on behalf of the person driving the agent, through OAuth, token exchange, or Cross App Access. A shared credential is acceptable when the data is read-only, the same for everyone in the organization, and nobody needs the upstream system to say which person asked. Anything that writes, returns data that differs by person, or must be attributed upstream needs delegation.
shared credentials vs user-delegated identity
A shared service credential is one upstream key or token that an MCP server or agent presents for every caller. User-delegated identity gives each call a token issued on behalf of the person driving the agent, through OAuth, token exchange, or Cross App Access. A shared credential is acceptable when the data is read-only, the same for everyone in the organization, and nobody needs the upstream system to say which person asked. Anything that writes, returns data that differs by person, or must be attributed upstream needs delegation.
Every Model Context Protocol (MCP) server that reaches a real system has to answer a second identity question after “who is calling?”: which credential does the server present to the API behind it? The answer is either one credential for the whole server or one per person. Other Speakeasy resources make the case against long-lived shared keys in agent configs, covering non-human identity and task-scoped credentials. This page is the decision rule for the case they leave open, where a shared credential is a reasonable choice and where it stops being one.
The case for shared credentials deserves a fair hearing first. Many upstream APIs issue only organization-level keys, with no per-user OAuth at all. A shared key needs no consent screen, never fails because one person’s refresh token expired, and works for a scheduled agent that runs with no one signed in. For a tool that searches public documentation, per-user delegation adds token plumbing and buys no security, because every caller would receive the same answer under any identity. Choosing delegation everywhere by policy is how teams end up with consent fatigue and a backlog of servers nobody can connect.
What is the difference between a shared service credential and user-delegated identity?
A shared service credential is a static API key, a bearer token, or an OAuth token that the server obtains for itself with the client credentials grant, used for every caller. The upstream system sees one identity, usually an app or a service account, and applies that identity’s permissions to every request.
User-delegated identity, often called delegated access, means each request reaches the upstream with a token that names the person behind the agent. The token comes from one of three places: an OAuth grant that the person approved for that service, a token exchange that converts the person’s existing token into one for the downstream service, or an identity provider grant through Cross App Access. The upstream applies that person’s permissions and writes that person’s name into its log.
| Property | Shared service credential | User-delegated identity |
|---|---|---|
| Who the upstream sees | One app or service account | The person who drove the agent |
| Permissions applied upstream | The credential’s, for every caller | Each person’s own |
| Effect of offboarding a person | None on the credential | New tokens for that person stop |
| Setup per person | None | A consent step, unless the identity provider brokers it |
| Works with no user present | Yes | Only while a stored refresh token or delegation stays valid |
| Upstream support required | An API key or client credentials | Per-user OAuth, token exchange, or Cross App Access |
The two models sit on top of a separate decision about who may call the server at all. A gateway can require every person to sign in, apply per-tool policy to them, and still use one shared credential upstream. That combination gets its own section below because it changes the answer for several of the tests.
When is a shared service credential good enough?
A shared credential is good enough when three conditions hold together: the tools only read, the data is the same for everyone in the organization, and no one needs the upstream system’s own log to name the person who asked. Each condition removes one of the four failure modes. Read-only tools cap the blast radius at disclosure. Organization-wide data means no caller sees anything they could not already see, which keeps least privilege intact. No upstream attribution requirement means the shared name in the upstream log costs nothing.
Typical servers that pass all three:
- A documentation or code search server over content every employee can read.
- A status, pricing, or public-data API that returns the same answer to any caller.
- An internal knowledge base whose access model is “everyone in the company”.
- A third-party API that only issues one organization key, used read-only.
A dedicated identity for a scheduled job is a related but different case. A nightly agent that summarizes yesterday’s incidents acts for the organization, not for a person, so there is no user to delegate from. It should still get its own credential with a named owner rather than a key shared with interactive users, which is the service or workload authority pattern.
The conditions fail more often than they look. An internal wiki that “everyone can read” frequently has restricted spaces. A CRM that a sales team uses read-only still scopes records by territory. When the upstream has any per-person permission model, a shared credential with enough access to serve every caller is broader than any single caller’s grant.
When does an agent need user-delegated identity?
An agent needs user-delegated identity when any of the four tests fails. The common triggers:
- The tools write. Creating issues, sending email, issuing refunds, or merging code. A leaked shared credential with write scope is a standing ability to act as the organization.
- The data differs by person. Email, calendars, files, CRM records, and support tickets all return different results to different people. A shared credential either returns too much or has to be scoped so narrowly that it is useless for most callers.
- The upstream enforces its own permissions. GitHub, Linear, Salesforce, and Google Workspace already know who may do what. Delegation lets them keep enforcing it; a shared credential replaces their checks with whatever the credential holds.
- The upstream record must name a person. Change management, financial controls, and incident response often need the system of record to show who acted, not which integration.
The MCP specification also rules out the shortcut of forwarding the caller’s own token. The MCP security best practices describe token passthrough as an anti-pattern that the authorization specification explicitly forbids, and state that MCP servers must not accept tokens that were not issued for them. Delegation therefore means minting or holding a separate token issued for the downstream service.
How do attribution, blast radius, least privilege, and offboarding compare?
The four tests come out differently for each model, and the differences compound once an agent chains several tool calls.
Attribution
With a shared credential, the upstream log attributes every call to the credential. If an agent deletes a record, the upstream can say which integration did it but not which person asked the agent to. With delegation, the upstream log names the person, and the gateway’s log can add which client acted for them. The composite identity page covers what a full record of person, agent, and client contains.
Blast radius
A shared credential has to cover every task any caller might run, so its scope is the union of all of them. If one team needs read access and another needs write access to the same service, the shared credential has write access, and anyone who extracts it from a config, a log, or a compromised dependency inherits that. A delegated token is limited to one person’s grant at one service, and tokens minted by token exchange or Cross App Access are short-lived by design.
Least privilege
Least privilege with a shared credential has to be enforced somewhere other than the upstream, because the upstream sees only one principal. A gateway can do this by filtering which tools each person may call, but it cannot narrow the data a permitted tool returns. Delegation keeps least privilege where the upstream already enforces it, per record and per field.
Offboarding
A delegated token stops working when the identity provider stops issuing tokens for the person, though tokens already issued typically remain valid until they expire. A shared credential is unaffected by anyone leaving. If the departing person could read the credential, rotating it is the only way to revoke their copy, and rotation breaks every other caller until the new value is in place.
Is a shared credential behind per-user sign-in a middle ground?
Yes, and for many internal servers it is the right answer. In this pattern, every person signs in to the gateway through the organization’s identity provider before they reach the MCP server. The gateway decides per person which servers and tools they may call, records each tool call against that person, and then calls the upstream with the shared credential.
This pattern changes the outcome of three tests. Attribution exists in the gateway’s own logs, even though the upstream log still shows the shared identity. Least privilege applies at the tool level, so a person allowed only search_docs cannot call delete_page on the same server. Offboarding works for access through the gateway, because a deprovisioned person can no longer sign in to reach the server.
What it does not change is anything outside the gateway. The upstream’s own permission checks still see one principal, so data-level least privilege is gone. The upstream’s own audit trail still names the integration. And the credential’s blast radius is the same as before if it leaks, because the upstream accepts it from anyone.
Cloudflare documents the same trade-off. In MCP Server Portals, the Require user auth setting decides whether each user logs in to an OAuth-protected server with their own credentials or whether everyone connected to the portal reaches it through the server’s admin credential. Its documentation also notes that users blocked at the portal can still reach a server by its direct URL unless Cloudflare Access is configured as that server’s OAuth provider. The same limit applies to any gateway, because its controls cover only the traffic that passes through it.
How does user delegation work: OAuth, token exchange, and Cross App Access?
Three mechanisms deliver a per-person token to the upstream. They differ in who approves the access and how much the upstream has to support.
Per-user OAuth grants
Each person connects each upstream service once through that service’s OAuth authorization code flow, and the gateway stores the resulting access and refresh tokens against the person. This works with any upstream that supports OAuth, which is most SaaS APIs with an MCP server. The cost is one consent step per person per service, and grants that live at each service rather than in one place an administrator can review.
OAuth token exchange (on-behalf-of)
RFC 8693 defines OAuth token exchange, the standard behind most on-behalf-of flows. The gateway presents the token that identifies the calling user to an authorization server and receives a new token scoped to the downstream audience. The person signs in once, and every downstream service that trusts the same authorization server gets a token that names them. The requirement is on the downstream side: its authorization server has to trust the issuer of the user’s token and support the exchange.
Cross App Access and enterprise-managed authorization
Cross App Access (XAA) is the informal name for the Identity Assertion JWT Authorization Grant, an IETF OAuth working group draft authored by contributors from Okta and Ping Identity. An application exchanges the identity assertion it received at single sign-on for a short-lived grant from the identity provider, called an ID-JAG, and redeems it at the downstream authorization server for an access token. The MCP Enterprise-Managed Authorization extension profiles this for MCP, so the identity provider decides centrally which people may reach which MCP servers and the person sees no per-service OAuth prompt.
Cross App Access moves consent from each person to the identity provider administrator, which is what enterprises usually want. Its constraint is adoption: the grant is still an Internet-Draft, and it only works when the downstream service’s authorization server accepts ID-JAGs, so most organizations will run it alongside per-user OAuth for services that have not implemented it.
How do MCP gateways handle shared and delegated credentials?
Most current MCP gateways support both models. They differ in where credentials live and which delegation mechanisms they implement.
- Cloudflare MCP Server Portals. Users sign in to the portal through Cloudflare Access, and servers can be unauthenticated, protected by OAuth, or configured with a static bearer token. The Require user auth setting chooses per server between each user’s own OAuth login and a shared admin credential. Cloudflare’s documentation also states that independent MFA, purpose justification, and temporary authentication are not enforced for servers authorized through a portal.
- Docker MCP Gateway. Docker’s MCP Toolkit gateway and the local Docker Sandboxes gateway run on the developer’s machine. In the MCP Toolkit, shared profiles exclude credentials, so each team member authorizes separately after pulling a profile, which makes per-user identity the default. Docker’s documentation also notes that OAuth credentials are shared across all of a user’s profiles, so using different accounts for different projects means revoking and reauthorizing. The Docker Sandboxes gateway keeps OAuth credentials and header secrets on the host, outside the sandboxed agent.
- IBM ContextForge. ContextForge, an open-source gateway, stores Authorization Code tokens per gateway and per user and also supports the client credentials grant for shared machine-to-machine access. Its OAuth design adds RFC 8693 token exchange for on-behalf-of calls. The identity propagation guide says token exchange audit events go to the structured log today, with dedicated audit columns planned as a follow-up.
- Kong AI MCP OAuth2 plugin. By default, the plugin strips the incoming access token before forwarding a request upstream, which prevents passthrough. From Kong Gateway 3.14, it can exchange the validated token for one issued by a different authorization server or with different scopes, and it can map token claims to upstream headers so an upstream that trusts the gateway receives the caller’s identity.
The pattern across vendors is that the per-server choice exists almost everywhere. What varies is whether delegation requires each person to connect each service, whether the gateway can broker tokens through the identity provider, and whether the gateway’s record of the caller survives when the upstream sees a shared identity.
What are the trade-offs of user-delegated identity?
Delegation has real costs, and a decision rule that ignores them will push teams back to shared keys.
- Upstream support. Many APIs offer only organization keys. For those, delegation is not available, and the realistic choice is a shared credential behind a gateway sign-in.
- Consent and connection fatigue. Per-user OAuth asks each person to connect each service. Token exchange and Cross App Access remove that step, but only for services whose authorization servers support them.
- Runtime dependency on the identity provider. Token exchange and Cross App Access call the identity provider on renewal. An identity provider outage or a policy change can stop tool calls that a static key would have served.
- Refresh failures. Per-user tokens expire and refresh tokens get revoked. Each failure surfaces to one person as a reconnect prompt, which is better for security and worse for anyone running a long agent task.
- Unattended agents. A scheduled or background agent with no one signed in needs either a stored delegation that outlives the session or its own workload identity. Neither is free to operate.
- Revocation is not instant. Deprovisioning stops new tokens, but downstream tokens already issued usually stay valid until they expire.
How do you decide for a given MCP server?
Work through the questions in order. The first “yes” decides the model.
- Does any tool write, delete, send, or pay? Use user-delegated identity.
- Does the upstream return different data to different people, or enforce its own per-user permissions? Use user-delegated identity.
- Must the upstream system’s own record name the person? Use user-delegated identity.
- Does the upstream offer only an organization key? Use a shared credential behind a gateway sign-in, restrict who may connect, and limit the key to read scopes. Revisit when the upstream adds OAuth.
- Is the agent acting for the organization with no person behind it? Give it a dedicated workload credential with a named owner, not a key shared with interactive users.
- None of the above? A shared, read-only credential behind a gateway sign-in is reasonable.
Among the delegation mechanisms, prefer Cross App Access where the downstream supports it, then token exchange where the downstream trusts the organization’s issuer, then per-user OAuth. That order runs from least to most work for each person and from most to least central control for administrators. Per-user OAuth is the fallback that works with the most upstreams, because it asks the least of them.
A note on Speakeasy
The Speakeasy AI Control Plane makes the upstream credential a per-server setting in its MCP gateway. On a remote server, the Identity section offers User Identity, where each person signs in to the upstream as themselves and the platform stores their OAuth token, and Service Account, where every caller shares one credential, either a static key or an access token the platform obtains with the OAuth client credentials grant (upstream credentials, changelog). For organizations on Okta, Enterprise Managed Auth uses Cross App Access to exchange each person’s Okta identity for a downstream token when a tool call needs one, so services show as connected through the organization with no per-service OAuth prompt. The Okta use case walks through that setup.
Who may call a server is set separately from its upstream credential, on the server’s Team Access tab, down to individual tools. That separation makes the middle-ground pattern from this page the default for shared credentials. People sign in, Team Access narrows who reaches the shared key, and Tool Logs record the user and client on every call. The static credential guide treats narrowing Team Access as a required step, because until it is done anyone the server’s access rules reach can act upstream as the credential’s owner.
Several limits apply. A Service Account token carries the app’s permissions at the upstream, not the caller’s, so the upstream’s own log and data-level checks see one identity, as described above. Enterprise Managed Auth supports Okta only and requires the downstream authorization server to support Cross App Access. Revoking a person’s session in the platform does not revoke the OAuth grant held at the upstream provider, and downstream tokens issued through Okta stay valid until they expire. And one expired per-user credential fails every tool served through that issuer until the person reconnects.
On Speakeasy’s managed gateway, shared credentials configured on remote servers are stored by the platform, encrypted at rest. Teams that want a backend credential to stay inside their own network can run the MCP server as a tunneled server, where the server holds its own configuration and private tunneled servers receive a signed JWT describing each authenticated caller, so the internal server can apply its own per-user policy. Making the client-facing MCP URLs reachable only from a private network is a separate step: Tailscale private network access requires an Enterprise organization, and the private MCP gateway page covers how that compares with self-hosted and tunneled designs.
If you are sorting your MCP servers into the ones that can share a key and the ones that cannot, we’d like to hear where the line falls for you. Talk to us.