MCP authentication
Choose agent keys, OAuth 2.1, or Agent Auth and handle revocation.
Choose a service credential for unattended work or a delegated method when a human should approve access.
| Method | Use |
|---|---|
| Agent key | Organization-owned service principal with explicit capability permissions and scopes |
| Agent Auth | User-approved delegated capability grant using live human access |
| OAuth 2.1 | Authorization Code with PKCE and user consent |
Credential precedence
A nonempty agent x-api-key is attempted first. Without one, a Bearer is checked as Agent Auth and then OAuth. Use one method per request.
Agent keys must contain at least one allowlisted capability permission and no permission outside the MCP capability set. Tool expressions and target scopes—not a universal backend.read rule—control listing and execution.
Delegated Agent Auth and OAuth use the human’s live permission union. Revocation or narrowing takes effect on the next request.
OAuth discovery
Start at /.well-known/oauth-protected-resource and follow the advertised authorization server. Do not hard-code authorization paths.
Advertised scopes are exactly:
openid profile email offline_accessCMS permissions such as content.read are not OAuth scopes. Accepted resource audiences cover the configured Management API origin, its slash form, /agent/mcp, and the issuer; unrelated audiences fail authentication.
A change_status call carries an approval requirement for destructive publication and still checks the exact transition permission. Use the client and authorization flow’s supported approval mechanism; do not treat tool visibility as approval.