3 routes
/grants
3 routes.
Apps the user connected through OAuth.
GET /v1/grants
List connected apps
Ordered (createdAt desc, id). A connection whose session has ended (revoked elsewhere, replaced by a new connection of the same app, or refresh-token reuse) is not listed.
Scopes: sessions:read
Query
| parameter | type | notes | |
|---|---|---|---|
limit |
integer | optional | min 1, max 200 |
cursor |
string | optional | max 4096 chars |
Response
- 200 GrantList. One page of OAuth grants.
Errors: grant_expired * grant_revoked * unauthorized * forbidden_scope * validation_failed * rate_limited * internal
PATCH /v1/grants/{id}
Change a connected app’s permissions (app session only)
The same operation as PATCH /keys/{id}, on a connected app: it REPLACES the grant’s scopes, the app’s existing access and refresh tokens keep working, and they pick the new set up within a minute on REST, at once on a new MCP connection, and at once in the scope of the next refresh. First-party only. There is deliberately NO MCP tool for this: an AI connection must never be able to widen a key, or itself. An id that belongs to an access key rather than a connected app is 404.
Scopes: any valid credential First-party only. Not callable with an access key or an OAuth token, whatever scopes it holds.
Request body
| field | type | notes | |
|---|---|---|---|
scopes |
array of todos:read, todos:write, containers:read, containers:write, inbox:read, inbox:write, tags:read, tags:write, filters:read, filters:write, attachments:read, attachments:write, notes:read, notes:write, settings:read, settings:write, webhooks:write, sessions:read, sessions:write, tasks:read, tasks:write |
required | The scopes this credential carries from now on. REPLACES the whole set; at least one. tasks:read/tasks:write are umbrellas that do NOT include sessions:* or webhooks:write. The change reaches REST within a minute (the row is read per request and cached ≤ 60 s) and an MCP connection at its next connect. |
Response
- 200 Grant. The grant row with its new scopes.
Errors: grant_expired * grant_revoked * unauthorized * forbidden_scope * not_found * payload_too_large * unsupported_media_type * validation_failed * rate_limited * internal
DELETE /v1/grants/{id}
Disconnect an app
Scopes: sessions:write
Response
- 204 No body. Disconnected.
Errors: grant_expired * grant_revoked * unauthorized * forbidden_scope * not_found * rate_limited * internal