Connections

Change an OAuth connection's vault access

Replaces the vault levels of ONE grant (family_id) of an OAuth client. Takes effect at once: issued access tokens and every later refresh carry the new access, and the user's live sockets reconnect. Widening is allowed. A grant the client asked to be read only (mcp:read) cannot be given write: 422. Session-auth only.

patch/api/connections/oauth/{client_id}

Request

  • Base URL: https://api.engram.page
  • URL: https://api.engram.page/api/connections/oauth/{client_id}
  • Auth: HTTP bearer

Path parameters

client_idstring required

OAuth client id

Query parameters

family_idstring required

The grant to change

Request body

default_access'none' | 'read' | 'write'

Level for every vault not listed, including vaults you create later. Defaults to none. The credential must reach at least one vault now or later.

vault_accessobject

Level per vault id, replacing the credential's current levels. Every id must be one of your active vaults.

Example request

{
  "default_access": "none",
  "vault_access": {
    "<vault id>": "write"
  }
}

Response

The updated connection

cimd_urlstring nullable

CIMD metadata-document URL. Present only for clients that published one, in which case it is the client's public identifier and the reason it can be verified despite redirecting to loopback.

client_idstring nullable
connected_atstring date-time nullable
family_idstring uuid nullable

The grant lineage this row is. One OAuth client can hold several grants over different vault sets, each its own row; pass this to DELETE /connections/oauth/{client_id} to revoke only this one. Null for PATs.

first_ipstring nullable
first_user_agentstring nullable
key_idstring nullable
kindstring required
labelstring nullable

The user's own name for this connection, when they set one.

last_used_atstring date-time nullable
logostring nullable
namestring nullable
new_vaults'none' | 'read' | 'write'

The level this connection gets on vaults you create later.

redirect_uristring nullable

The redirect this grant's authorization code was delivered to. This, not redirect_uris, is what decides verified. Null for non-OAuth connections and for grants issued before it was recorded.

redirect_urisstring[] nullable

Every redirect the client registered. Informational only — a client may register several and choose one per authorization, so a vendor host appearing here proves nothing about this grant.

scopestring nullable
slugstring nullable
software_idstring nullable
software_versionstring nullable
vault_idsstring[] nullable

Vaults this connection may reach right now (read or write). Null means every vault, including ones created later. For a connection with per-vault levels this is resolved, not stored: the vaults vault_levels shows at read or write. Vaults created later get new_vaults, so read both for the full picture.

vault_namesstring[] nullable

Positional against vault_ids. An entry is null when the vault is gone or outside the caller's own scope.

verifiedboolean nullable

Example response

{
  "cimd_url": "https://claude.ai/.well-known/oauth-client",
  "kind": "oauth"
}

Changes

No recorded changes to this operation across all 1 revision of this API.