Skip to main content
MCP Gateway handles authentication at two independent layers. Understanding this separation is key to configuring secure access.

​
Two-Layer Architecture

LayerWho authenticatesMethods
Gateway AuthAgent → PortkeyAPI Key, Portkey OAuth, External IdP
Server AuthPortkey → MCP ServerOAuth Auto, Client Credentials, Headers
These layers are independent. An agent authenticates to Portkey with an API key. Portkey authenticates to Linear with OAuth. The agent never sees Linear’s OAuth tokens.

​
Gateway Authentication

Agents prove their identity to Portkey before accessing MCP servers.
How it works: Requests with an API key use API key auth. Requests with a JWT from an external IdP (with JWT validation configured) use JWT validation. Requests with neither trigger the OAuth flow. No configuration needed—just include an API key or don’t.

​
API Key

The simplest method. Create an API key in Portkey and include it in requests. 
{
  "headers": {
    "Authorization": "Bearer pk_xxx"
  }
}
API keys are scoped to workspaces. The key determines which MCP servers the request can access. Create keys in Settings > API Keys. The key must have mcp invoke permissions.

​
OAuth 2.1

For browser-based flows where users authenticate interactively. If no API key is provided, Portkey acts as the OAuth provider and initiates the consent flow. After authentication, your app receives a token to use for MCP requests. This is useful for:
  • End-user applications where users log in
  • Interactive tools like Claude Desktop or Cursor (when not using API keys)
  • User-level attribution without managing API keys
See OAuth for details.

​
External IdP (Bring Your Own Identity)

Use existing identity providers (Okta, Auth0, Azure AD, Cognito). Configure Portkey to validate tokens from your IdP. Users authenticate with existing identity systems—no Portkey accounts needed. This is useful when:
  • You have an existing IdP and want SSO
  • Users who aren’t in Portkey need MCP access
  • Compliance requires your own identity infrastructure
See External OAuth for setup.

​
MCP Server Authentication

Portkey needs credentials to access upstream MCP servers. Configure this when adding a server.

​
OAuth Auto

For MCP servers that support OAuth 2.1 with dynamic client registration. Portkey handles the full OAuth flow automatically. When a user first calls a tool, Portkey initiates OAuth with the MCP server. The user completes consent (e.g., authorizing access to their Linear account). Portkey stores and refreshes tokens automatically. Each user gets their own OAuth tokens. User A’s Linear access is separate from User B’s. Customize the OAuth client metadata Portkey uses during registration. See OAuth Client Metadata.

​
Client Credentials

For MCP servers using OAuth client credentials grant. You provide a client ID and secret when adding the server. Portkey fetches tokens and handles refresh. All users share the same credentials to the MCP server. Use this for shared resources, not personal data.

​
Custom Headers

For MCP servers using API keys or static tokens. Add headers when configuring the server. 
{
  "headers": {
    "Authorization": "Bearer api_key_xxx",
    "X-API-Key": "your_key"
  }
}
Portkey includes these headers with every request. All users share the same credentials. See Custom Auth for details.

​
Data Flow: Headers and Identity

Beyond authentication, Portkey supports passing contextual information to MCP servers:

​
Identity Forwarding

After authenticating a user, Portkey can forward their identity claims to MCP servers. MCP servers can then make authorization decisions without implementing OAuth themselves. Three methods:
  • Claims Header: JSON object with user claims
  • Bearer Passthrough: Forward the original token
  • Signed JWT: Portkey-signed JWT with claims (cryptographically verifiable)
See Identity Forwarding.

​
Header Forwarding

Forward headers from agent requests to MCP servers for distributed tracing, tenant context, or custom metadata. 
{
  "forward_headers": ["x-request-id", "x-trace-id", "x-tenant-id"]
}
See Forwarding Headers.

​
Choosing the Right Method

ScenarioGateway AuthMCP Server Auth
Internal developers using PortkeyAPI KeyOAuth Auto (per-user)
End customers with your IdPExternal OAuthOAuth Auto (per-user)
Service-to-service accessAPI KeyClient Credentials or Headers
Shared read-only resourcesAPI KeyCustom Headers
Use per-user OAuth when the MCP server accesses user-specific data (email, repos, messages). Each user authorizes their own access. Use shared credentials when the MCP server provides shared resources (knowledge bases, analytics). All users see the same data.

​
Credential Isolation

Credentials never cross boundaries. 
Agent knows:      Portkey API key
Portkey knows:    MCP server OAuth tokens, API keys, user identity claims
MCP Server knows: Its own credentials
Agents can’t see MCP server credentials. Compromised agent tokens don’t expose upstream access. Rotate MCP server credentials without updating agents.

​
Quick Reference

TopicDescription
OAuthPortkey’s built-in OAuth 2.1 authentication
External OAuthUse your own identity provider
JWT ValidationValidate JWTs from external IdPs
Identity ForwardingPass user identity to MCP servers
Forwarding HeadersPass headers from agents to MCP servers
OAuth Client MetadataCustomize OAuth registration
Custom AuthConfigure custom headers for MCP servers