Status: Stable.
Normative home:
oauth,credentials.
Why this exists
The host obtains, stores and refreshes the third-party tokens a connector node needs; a pack names a provider and scopes and never touches the grant. Here the host is an OAuth client; identity.md covers it as a protected resource.
Credentials
A host advertising credentials MUST resolve a { ref, scope } reference (schemas/v2/credential-reference.schema.json) at node execution and inject the material only into the node sandbox.
- The material MUST NOT appear in inputs, variables, events, the debug bundle or replay state (invariant
credential-payload-redaction). - A failed resolution is
credential_not_found,credential_forbidden(outside the caller's scope; fail closed) orcredential_scope_unsupported(a scope not incredentials.scopes). - With
credentials.sharing, every reference within a scope resolves one stored credential. - With
credentials.rotationtwo-key-overlap, old and new material both resolve during the grace window; after it the old failscredential_not_found. credentials.encryptionAtRestgates nothing.
Token lifecycle
A host advertising oauth:
- MUST perform only the grants in
oauth.grants. - MUST refuse to register a node whose
auth.provideror scope is not inoauth.providers(oauth_provider_unsupported,oauth_scope_unsupported). - Drives the redirect and callback host-side. The code, redirect URI,
stateand PKCE verifier MUST NOT enter a run-visible surface. - Persists tokens as a
credentialsentry at scopeuserorworkspace, and refreshes them host-side. - On terminal refresh failure, MUST emit
connector.auth-expiredand fail the node withconnector_auth_expired, unless it advertisesoauth.credentialInterrupt.
The authorization-code client
On every authorization_code grant the host MUST:
- send PKCE with
S256and neverplain, omitting PKCE only for a provider advertised withpkce: "unsupported"; - send a fresh
stateof at least 128 bits from a CSPRNG, bound host-side to the initiating Subject and the provider, with a lifetime of at most 10 minutes, and refuse a callback whosestateis absent, unknown, reused or expired, making no token request for it; - complete the callback only for the initiating Subject (invariant
oauth-same-user-binding): store the credential under the Subject bound tostate, and if the Subject authenticated on the callback request (session or bearer) differs from it, refuse and store nothing; - validate
issper RFC 9207 §2.4 where the provider's issuer is known (oauth.providers[].issuer), and otherwise give the provider a redirect URI no other provider shares (RFC 9700 §4.4.2); - use one fixed, registered redirect URI per provider.
MCP-reach providers
Where the provider is reached as an MCP server:
- The host MUST also send
resource(RFC 8707), the server's canonical URI, in both requests. - The host MUST refuse a provider whose authorization-server metadata omits
S256. - It fetches the server's Protected Resource Metadata (RFC 9728) only from URLs derived from the manifest's server URL.
- Discovery verifies and never selects. A discovered issuer or endpoint that differs from the manifest's, or from the tuple pinned at registration, MUST be refused
connection_auth_metadata_mismatch. A grant for such a provider whose manifest declares noissuerMUST be refused the same way.
This binds a host-configured provider as well as a connection-pack one: the configured server URL and issuer stand in for the manifest's, pinned when the host loads that configuration.
The credential interrupt
A host advertising oauth.credentialInterrupt MUST suspend the node with a credential interrupt (interrupt.md) instead of failing it when a node declaring auth: { type: "oauth2", provider, scopes } is about to run and:
- no credential resolves for the Subject, provider and scopes (
reason: "missing"); - one resolves with fewer scopes (
"insufficient_scope"); or - refresh failed terminally (
"expired").
Then:
connectUrlMUST be host-owned, MUST NOT be pre-authenticated, and MUST complete only for the initiating Subject.- The host resolves the interrupt when the grant completes. A resolve of
authorizedMUST be refused400 validation_errorunless a credential now resolves. declinedfails the node withconnector_auth_declined.- A host that binds a node to one credential reference (such as a connection) reads "resolves" as that reference resolving with the node's scopes, carries it as
credentialRef, and still completesconnectUrlonly for the initiating Subject.
Sources: RFCs 0046, 0047, 0199.