MCP authentication
Choose agent keys, OAuth 2.1, or Agent Auth and handle revocation.
Choose a service credential for unattended management work or a delegated method when a human should approve access. These methods authenticate the Management MCP at /agent/mcp; the Delivery API’s read-only Context MCP instead uses a delivery x-api-key or Preview Bearer.
| 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. Agent Auth clients sign a fresh, short-lived JWT with a unique replay identifier for every request. Only active capability grants project tools; inspect also gates management resources, while control_operation gates MCP Tasks. Agent/grant revocation, OAuth client disablement, role removal, or scope narrowing takes effect on the next request and is rechecked again before queued execution.
A delegated client with live apiKey.create permission may request a narrowly scoped Delivery key through a human-approved Candidate. The same delegated credential can claim the resulting secret once. Organization-owned Agent keys cannot mint or claim credentials, and delegated clients cannot request Agent keys.
OAuth discovery
Start at /.well-known/oauth-protected-resource and follow the advertised authorization server. Do not hard-code authorization paths.
Advertised scopes are:
openid profile email offline_access
management:inspect management:propose management:execute management:controlThe four management intent scopes map to Jetrepo’s four stable Management tools. Domain permissions such as content.read remain live Organization-role permissions and are not OAuth scopes.
OAuth consent binds the delegated grant to one selected Organization. The only accepted Management resource audience is the canonical /agent/mcp URL; Backend and Environment IDs remain per-call scope rather than token audiences. Access tokens expire after 10 minutes and refresh authorization after 30 days.
Open Organization management → Connections to inspect or revoke a grant. Jetrepo rechecks the consent, OAuth client, user, Organization, live roles, and target scope on every call and before queued consequential execution. Revocation also invalidates still-unexpired self-contained access tokens at the Management boundary.
A Content lifecycle Operation Definition still checks its exact requester permission and effective publication policy when proposed and executed. Human Approval is recorded through control_operation; a client’s tool confirmation, authorization consent, or visible tool list is not Approval.