Change an OAuth connection's vault access

PATCH

/connections/oauth/{client_id}

curl --request PATCH \
  --url 'https://api.engram.page/connections/oauth/example?family_id=example' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "default_access": "none", "vault_access": { "<vault id>": "write" } }'

• Production

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.

Authorizations

• bearerAuth

Parameters

Path Parameters

client_id

required

string

OAuth client id

Query Parameters

family_id

required

string

The grant to change

Request Body^required

New access

Media typeapplication/json

UpdateAccessRequest

object

default_access

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.

string

Allowed values: none read write

vault_access

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

object

key

additional properties

string

Allowed values: none read write

Example

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

Responses

200

The updated connection

Media typeapplication/json

Connection

object

cimd_url

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.

string

nullable

client_id

string

nullable

connected_at

string format: date-time

nullable

family_id

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.

string format: uuid

nullable

first_ip

string

nullable

first_user_agent

string

nullable

key_id

string

nullable

kind

required

string

label

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

string

nullable

last_used_at

string format: date-time

nullable

logo

string

nullable

name

string

nullable

new_vaults

The level this connection gets on vaults you create later.

string

Allowed values: none read write

redirect_uri

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.

string

nullable

redirect_uris

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.

Array<string>

nullable

scope

string

nullable

slug

string

nullable

software_id

string

nullable

software_version

string

nullable

vault_ids

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.

Array<string>

nullable

vault_levels

What this connection may do in each of your vaults, resolved now. Every vault you can see is listed, none included. read = search and read, write = also change notes and the vault.

Array<object>

object

level

required

string

Allowed values: none read write

vault_id

required

string format: uuid

vault_name

string

nullable

vault_names

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

Array<string>

nullable

verified

boolean

nullable

Example

{
  "cimd_url": "https://claude.ai/.well-known/oauth-client",
  "kind": "oauth",
  "new_vaults": "none",
  "vault_levels": [
    {
      "level": "none"
    }
  ]
}

400

Missing family_id

Media typeapplication/json

MessageError

object

error

required

string

Example

{
  "error": "not found"
}

404

No such connection

Media typeapplication/json

MessageError

object

error

required

string

Example

{
  "error": "not found"
}

422

Access the grant cannot have

Media typeapplication/json

Error

object

errors

One of:

string

string

object

object

Example ^generated

{
  "errors": {}
}