Upstream authentication
MCP clients authenticate to PolicyLayer with grant tokens. Upstream MCP servers authenticate separately.
The request flow is:
- The client sends
Authorization: Bearer <grant-token>to PolicyLayer. - PolicyLayer uses the grant to identify the server, grant, and policy.
- If policy allows the call, PolicyLayer forwards the request upstream with the server’s configured upstream credentials.
- The client’s grant token is not forwarded upstream.
Configure upstream authentication on the server detail page, in the OAuth and Static headers sections.
Headers PolicyLayer owns
PolicyLayer does not forward the incoming Authorization header upstream. The proxy consumes that header as the PolicyLayer grant token, then replaces it with the configured upstream credentials if the upstream needs them.
PolicyLayer also drops incoming cookies before forwarding requests. Control-plane browser state should not reach an MCP upstream.
Choose a mode
| Mode | Use when | What PolicyLayer injects upstream |
|---|---|---|
| OAuth | The upstream MCP server advertises OAuth and should be connected once for the server. | Authorization: Bearer <upstream-access-token> |
| Static headers | The upstream expects fixed headers such as API keys, tenant IDs, or API-version headers. | The configured header keys and values |
| None | The upstream does not require authentication, or it is already gated somewhere else. | No upstream credential |
OAuth
Use OAuth when the upstream MCP server supports an OAuth authorization flow.
The dashboard shows an OAuth section unless discovery confirms the upstream does not require OAuth.
Click Connect to start the upstream OAuth flow. PolicyLayer redirects your browser to the upstream authorization server, completes the authorization-code flow, and stores the returned access token and any refresh token encrypted at rest.
At runtime, the proxy decrypts the upstream access token and injects it as the upstream Authorization header. If the token is close to expiry, PolicyLayer refreshes it before forwarding the request.
OAuth has three dashboard states:
| State | Meaning |
|---|---|
connected | Upstream OAuth credentials are available. |
disconnected | No upstream OAuth token is connected. |
error | Token refresh failed. Use Reconnect to authorize again. |
Use Reconnect to run the flow again. Use Disconnect to clear stored OAuth tokens and cancel pending OAuth flows for that server.
Static headers
Static headers are fixed key-value pairs injected on every proxied request to the upstream server.
Common examples:
Authorization: Bearer <upstream-api-token>X-Org-ID: <tenant-id>Stripe-Version: <api-version>
PolicyLayer stores static headers encrypted at rest. Only admin users can view or edit them in the dashboard.
Header audit events record which keys were added, removed, or changed. They do not record header values.
If OAuth is connected and static headers also include Authorization, the OAuth bearer token wins for the forwarded request. If OAuth is not connected, a static Authorization header is forwarded like any other configured header.
No upstream auth
If the upstream requires no authentication, leave OAuth disconnected and static headers empty. The client still authenticates to PolicyLayer with a grant token.
Access control
Upstream authentication is server configuration. It is limited to admin users.
policy_manager users can write and attach policies, but they cannot connect OAuth, disconnect OAuth, view static headers, or edit static headers. viewer users cannot change upstream authentication.