Contract 1.7.0 · Local previewRead Markdown

Authentication and permissions

Cadence owns the OAuth authorization server. MCP access uses opaque bearer tokens bound to one account, client and exact resource URL. An ordinary web session is not an MCP token.

Discovery and registration

An unauthenticated MCP request returns 401 with a WWW-Authenticate challenge naming resource_metadata. For the planned issuer, discovery routes are:

The metadata advertises /oauth/authorize, /oauth/token, /oauth/register and /oauth/revoke. Prefer discovery over hardcoding endpoints. The implementation supports public clients with token_endpoint_auth_method none. It does not support client secrets or private_key_jwt.

CIMD uses an HTTPS client_id URL containing public client metadata. Cadence fetches bounded JSON, validates redirects and rejects private-network addresses. Metadata caching respects freshness up to one hour. DCR accepts a public-client registration at /oauth/register when the client lacks CIMD. Unused DCR registrations expire after 24 hours. Client metadata and names do not establish verification; consent labels unverified clients.

Authorization code with PKCE

  1. Create state and a fresh PKCE verifier. Derive an S256 code challenge.
  2. Request response_type=code, client_id, redirect_uri, scope, state, code_challenge, code_challenge_method=S256, and resource equal to the MCP URL.
  3. The user signs in with Google on Cadence, checks the client and redirect host, and chooses permissions.
  4. Check state and iss on the callback. Exchange the single-use code at /oauth/token with the verifier, matching client_id, redirect_uri and resource.
  5. Send the access token only in the Authorization: Bearer header.

Registered redirect URIs must match exactly, except supported native loopback port matching. Browser-bound pending requests and codes expire after ten minutes. Denial returns access_denied without creating a grant. Reusing a code revokes its token family.

Scope Effect
cadence.read Required. Reads the included tracking data.
cadence.occurrences.write Optional. Changes Occurrence status and notes.
cadence.behaviors.write Optional. Creates, edits, archives and restores Behaviors.
offline_access OAuth request option for refresh tokens, not a tool permission.

Consent can remove either write scope. Inspect granted_scopes from get_account_context before offering an edit. Missing permission produces insufficient_scope and an authentication challenge. Reconnect and let the user approve the missing permission. Never silently broaden a grant.

Token lifetime and refresh

Access tokens expire after one hour. Refresh tokens rotate on every use, expire after 30 idle days, and cannot outlive their 90-day family. Store the replacement refresh token atomically. Serialize refresh attempts: replaying an old refresh token revokes the whole family.

Cadence stores token hashes. Clients must protect their own token storage and avoid URLs, logs, exports or shared files. A token for a different MCP resource fails verification.

Disconnect and Connected apps

In Cadence Settings, open Connected apps to review permissions, connection dates, last use and recent activity. Disconnect revokes the grant and tokens; the next request fails. Clients can also use /oauth/revoke. Reconnecting creates a new grant and does not reactivate revoked tokens.

The optional OpenAI profile marker is absent because its identity-only schema conflicts with Cadence’s account-context schema. Account labels and duplicate detection may be less reliable. All 16 tool schemas remain unchanged.