Connections¶
Tools the owner connected. A tool proposes shares (revoked://p) and,
once connected, reads the status of the links its proposals became and
receives the links the owner handed it. It reads the vault only where
the owner allowed allowVaultRead, and stores nothing here. It is connected from the app — the owner
authorizes, the tool exchanges a one-time code (PKCE) for a token it
sends as X-Revoked-Connection. A connection lapses 90 days after the
owner last connected the tool.
POST /api/connections/authorize¶
Authorize a tool (from the app)
Auth: Session
Called by the owner's app after they agreed to connect a tool. Finds or
creates the connection for the tool's origin in the active workspace,
renews it for 90 days (tokens of a connection that had lapsed are
deleted, not revived), and returns a one-time code, valid for five minutes, bound to the tool's PKCE
challenge and return address. The app then opens the return address with
code and the tool's state.
Request body
application/json
| Field | Type | Notes |
|---|---|---|
clientId |
string | The tool's origin. |
clientName |
string | The name the tool gives itself; shown as a claim. |
redirectUri |
string | Where the code is delivered; must be on clientId's origin. |
allowRevoke |
boolean | Whether the tool may revoke the links its proposals became. Left out, a connection keeps what it had; a new one starts without it. |
allowHandOver |
boolean | Whether the tool may receive links the owner shares with it. Left out, a connection keeps what it had; a new one starts without it. A link can only be created with handedOver while this is set (link_hand_over_not_allowed otherwise), and the tool stops seeing the URLs it was given when it is taken away. |
allowVaultRead |
boolean | Whether the tool may read the owner's whole vault through /api/vault. Left out, a connection keeps what it had; a new one starts without it. Refused together with poll (connection_vault_polled), and a token collected by polling never reads the vault. |
permissions |
array of string | Permission keys from the catalogue the tool may act on: shares:read, shares:manage, requests:manage, attestations:issue, vault:read, vault:write. Anything else is refused with connection_permission_invalid, and a key the owner does not hold with permission_escalation. Replaces what the connection held, keeping the narrower allowRevoke and allowHandOver. The vault keys reach only the tool's sections, or the whole vault with allowVaultRead. |
section |
boolean | Give the tool a section of its own, named after it, where it may write records and files. Asking for it asks for vault:write unless permissions says vault:read. false takes the tool's vault access away and keeps the section: giving it back brings the same one. |
sections |
array of string | The owner's own sections the tool may read and not change. Refused with vault_section_invalid for any other. |
challenge |
string | PKCE S256 challenge, base64url. |
reuse |
boolean | Set when the owner was not asked again because the tool is already connected and another of their browsers wants in. Only issues a code: the connection keeps its name, permissions and expiry (allowRevoke and allowHandOver are ignored). Refused with connection_not_connected when there is no live connection for the origin. |
poll |
boolean | Set when the page that asked collects the answer itself: the tool named the owner's server in its link (poll), so the app opens no return address and the page exchanges its verifier alone at /api/connect/token. No return address ties such an answer to one of the owner's own browsers, so the app never sets it unasked, reuse included: the owner compares a code both ends derive from the challenge (the first three bytes of its SHA-256, as 83C-047). |
Responses
| Status | Meaning |
|---|---|
200 |
The one-time code. |
400 |
connection_client_invalid, connection_redirect_invalid, connection_challenge_invalid, connection_vault_polled, connection_permission_invalid, permission_escalation or vault_section_invalid. |
409 |
connection_not_connected: reuse was set, but the tool is not connected or its connection has lapsed. connection_paused: the owner paused the tool, and connecting again doesn't lift that. |
Response fields
| Field | Type | Notes |
|---|---|---|
code |
string | |
connectionId |
string |
POST /api/connect/token¶
Exchange a code for a connection token (the tool)
Unauthenticated
Callable with no credential.
Spends the one-time code — right or wrong, a code works once — and, when the verifier matches its challenge and the return address matches, returns a token for this browser. Rate-limited per IP.
Without code, the page asks for an answer the app left for it
(poll on authorize): it is found by the verifier's challenge, and
given only to a request whose Origin is the tool's own. Until the
owner has answered there is nothing to find, and the reply is 202;
a tool asks again every few seconds, for as long as an answer is kept
(five minutes). An answer issued as a code is never found this way.
Request body
application/json
| Field | Type | Notes |
|---|---|---|
code |
string | Left out by a page that collects its answer itself. |
verifier |
string | The PKCE verifier. |
redirectUri |
string | The same return address the code was issued for. |
Responses
| Status | Meaning |
|---|---|
200 |
The token, shown once. |
202 |
No code was sent, and the owner has not answered yet. |
400 |
connection_grant_invalid. |
429 |
rate_limited. |
Response fields
| Field | Type | Notes |
|---|---|---|
token |
string | |
connection |
object |
GET /api/connection¶
The status of what the tool proposed
Auth: Connection
The links, requests, attestations and attestation checks the tool's
proposals became. url appears only on links the owner handed to the
tool, and only while they can be opened. A request never carries its
address or its answers, and an attestation never its claims or offer
token. A check carries its verdict once answered, with the claims the
other person chose to show. A tool stores nothing here: ref and
label are what it set on the proposal.
Responses
| Status | Meaning |
|---|---|
200 |
The connection as the tool may see it. |
401 |
connection_unauthorized, or connection_expired once the connection has lapsed. |
403 |
connection_paused: the owner paused the tool. Keep the token. |
Response fields
| Field | Type | Notes |
|---|---|---|
id |
string | |
clientId |
string | |
clientName |
string | |
expiresAt |
string | When the connection lapses, 90 days after the owner last connected the tool. Only connecting again from the app renews it. |
allowRevoke |
boolean | Whether the owner lets the tool end what it proposed or created. |
allowHandOver |
boolean | Whether the owner lets the tool receive links. |
permissions |
array of string | The catalogue keys the tool holds in full. |
vaultAccess |
string (` \|read\|write`) |
|
section |
string | The tool's own section, if it has one. |
sectionOff |
boolean | Whether the owner switched the tool's own section off: it then neither reads nor writes there. |
sections |
array of string | Sections the owner added, which the tool may read. |
allowVaultRead |
boolean | Whether the owner let the tool read the whole vault. |
vaultReadable |
boolean | Whether this token reaches the whole vault: never one collected by polling. |
links |
array of object | |
requests |
array of object | |
attestations |
array of object | |
checks |
array of object |
DELETE /api/connection¶
Disconnect (the tool)
Auth: Connection
Deletes the connection. The owner's links stay; they no longer name the tool.
Responses
| Status | Meaning |
|---|---|
204 |
Disconnected. |
401 |
connection_unauthorized, or connection_expired once the connection has lapsed. |
403 |
connection_paused: the owner paused the tool. Keep the token. |
POST /api/connection/links/{id}/revoke¶
Revoke one of the tool's links (the tool)
Auth: Connection
Ends a link the tool's proposal became, or one it created. Only when
the owner allowed it (allowRevoke, or shares:manage).
The owner is notified as for any revocation. Revoking a link that is
already revoked succeeds.
Parameters
| Name | In | Required | Notes |
|---|---|---|---|
id |
path | yes |
Responses
| Status | Meaning |
|---|---|
200 |
The link as the tool may see it, now revoked. |
401 |
connection_unauthorized or connection_expired. |
403 |
connection_revoke_not_allowed, or connection_paused while the owner has the tool paused. |
404 |
Not a link of this tool. |
POST /api/connection/drafts¶
Suggest values for a proposal (the tool)
Auth: Connection
Holds text values the tool heard from the owner, so a share proposal
can offer them prefilled. Returns a draft id for the proposal link
(draft=<id>); the link never carries the values. Drafts are kept in
the server's memory only, for one hour, and are gone on restart.
Nothing is saved to the vault: the app offers a value only for a key
the vault does not hold yet, and the owner saves it. The audit log
(tool_drafted_values) names the keys, never the values. At most 20
open drafts per connection.
Request body
application/json
| Field | Type | Notes |
|---|---|---|
values |
object | 1-50 keys ([a-z0-9_-]{1,64}), each non-empty text of at most 4000 characters without control characters other than line breaks and tabs. |
Responses
| Status | Meaning |
|---|---|
200 |
The draft. |
400 |
The values are refused whole when any part is malformed. |
401 |
connection_unauthorized or connection_expired. |
403 |
connection_paused while the owner has the tool paused. |
429 |
Too many open drafts for this connection. |
Response fields
| Field | Type | Notes |
|---|---|---|
id |
string | 24 characters, a-z and 0-9. |
expiresAt |
string |
GET /api/connections/drafts/{id}¶
Read a tool's suggested values (the owner)
Auth: Session
The values a connected tool suggested, for the proposal screen. Only the owner of the tool's connection reads them, and not while the connection is paused or expired.
Parameters
| Name | In | Required | Notes |
|---|---|---|---|
id |
path | yes |
Responses
| Status | Meaning |
|---|---|
200 |
The draft. |
401 |
Not signed in. |
404 |
No such draft for this person, or it expired. |
Response fields
| Field | Type | Notes |
|---|---|---|
id |
string | |
connection |
string | |
clientName |
string | |
values |
object | |
expiresAt |
string |
DELETE /api/connections/drafts/{id}¶
Discard a tool's suggested values (the owner)
Auth: Session
Drops the draft once the proposal is created or declined. Succeeds when it is already gone.
Parameters
| Name | In | Required | Notes |
|---|---|---|---|
id |
path | yes |
Responses
| Status | Meaning |
|---|---|
204 |
Discarded, or already gone. |
401 |
Not signed in. |
GET /api/connection/vault¶
List the vault (the tool, older path)
Auth: Connection
The same as GET /api/vault, kept for tools written against it.
Responses
| Status | Meaning |
|---|---|
200 |
As GET /api/vault. |
403 |
As GET /api/vault. |
GET /api/connection/vault/{id}¶
Read one record (the tool, older path)
Auth: Connection
The same as GET /api/vault/{id}.
Parameters
| Name | In | Required | Notes |
|---|---|---|---|
id |
path | yes |
Responses
| Status | Meaning |
|---|---|
200 |
As GET /api/vault/{id}. |
404 |
As GET /api/vault/{id}. |
POST /api/connection/links¶
Create a share (the tool)
Auth: Connection
Shares records and sections within the tool's reach, at once. Needs
shares:manage. The share is the owner's and joins the connection, as
a proposal the owner saved does; the owner can pause, change or revoke
it in the app. A record or section out of reach answers 404, like a
missing one.
Request body
application/json
| Field | Type | Notes |
|---|---|---|
label |
string | |
password |
string | Optional password; stored hashed. |
records |
array of string | |
sections |
array of string | |
expiresAt |
string | Left out, the share does not expire. |
maxViews |
integer | |
ref |
string | The tool's own reference, returned with the link's status. |
Responses
| Status | Meaning |
|---|---|
201 |
The link as the tool sees it, with its url. |
403 |
connection_not_permitted, or connection_paused. |
404 |
record_not_found: a record or section out of reach. |
POST /api/connection/requests¶
Create a request (the tool)
Auth: Connection
Asks for data in the owner's workspace, at once. Needs
requests:manage. identity names the identity it asks as; left out,
the workspace's primary one. template is a template id or name in the
workspace. The answers land with the owner as for any request; the
tool sees where the request stands, never the answers. url is the
app link to pass to whoever should answer. Refused to a token
collected by polling (connection_polled): whoever sent the owner a
connect link can read them its check code, and a request asks
strangers for data in the owner's name.
Request body
application/json
| Field | Type | Notes |
|---|---|---|
label |
string | |
template |
string | |
identity |
string | |
expiresAt |
string | |
maxResponses |
integer | |
ref |
string |
Responses
| Status | Meaning |
|---|---|
201 |
The request as the tool sees it, with its url. |
403 |
connection_not_permitted, connection_polled, template_not_owned, identity_required, identity_not_owned or identity_revoked. |
GET /api/connection/sections¶
Read the tool's section groups and their current entries
Auth: Connection
Responses
| Status | Meaning |
|---|---|
200 |
Object containing sections and records, with current values. Only groups beneath the tool's enabled own-section grant. |
401 |
Not connected. |
403 |
Vault access or own-section grant unavailable. |
429 |
Read rate limit exceeded. |
POST /api/connection/sections¶
Create a group inside the tool's own section grant
Auth: Connection
Request body
application/json
| Field | Type | Notes |
|---|---|---|
name |
string | |
key |
string |
Responses
| Status | Meaning |
|---|---|
201 |
Section id, namespaced key suffix, name and empty records array. |
400 |
Invalid section name or key. |
401 |
Not connected. |
403 |
Vault write or own-section grant unavailable. |
429 |
Write rate limit exceeded. |
PATCH /api/connection/sections/{id}¶
Rename a tool group or attach/detach entries written by the tool
Auth: Connection
Parameters
| Name | In | Required | Notes |
|---|---|---|---|
id |
path | yes |
Request body
application/json
| Field | Type | Notes |
|---|---|---|
name |
string | |
records+ |
array of string | |
records- |
array of string |
Responses
| Status | Meaning |
|---|---|
204 |
Updated. |
400 |
Invalid section update. |
401 |
Not connected. |
403 |
Vault write not granted or a record was not written by this tool. |
404 |
Not this tool's group. |
429 |
Write rate limit exceeded. |
PATCH /api/connection/links/{id}¶
Replace the explicit record grant on a share created by this tool
Auth: Connection
Sections provide layout only. Pass every intended record id explicitly. Needs shares:manage and current vault reach for each entry.
Parameters
| Name | In | Required | Notes |
|---|---|---|---|
id |
path | yes |
Request body
application/json
| Field | Type | Notes |
|---|---|---|
records |
array of string | |
sections |
array of string |
Responses
| Status | Meaning |
|---|---|
200 |
Updated link status, as on GET /api/connection. |
400 |
Invalid update. |
401 |
Not connected. |
403 |
Share management not granted. |
404 |
Not this tool's share or content is out of reach. |
429 |
Write rate limit exceeded. |
POST /api/connection/requests/{id}/close¶
Close one of the tool's requests (the tool)
Auth: Connection
Stops a request the tool's proposal became from taking new answers.
The answers already given stay their responders' links. Only when the
owner allowed it (allowRevoke, or requests:manage). Closing a
closed request succeeds.
Parameters
| Name | In | Required | Notes |
|---|---|---|---|
id |
path | yes |
Responses
| Status | Meaning |
|---|---|
200 |
The request as the tool may see it, now revoked. |
401 |
connection_unauthorized or connection_expired. |
403 |
connection_revoke_not_allowed, or connection_paused while the owner has the tool paused. |
404 |
Not a request of this tool. |
POST /api/connection/attestations/{id}/revoke¶
Revoke one of the tool's attestations (the tool)
Auth: Connection
Revokes an attestation the tool proposed and the owner issued, or
withdraws its offer. Final: it reaches verifiers through the status
list, as when the owner revokes it. Only when the owner allowed it
(allowRevoke, or attestations:issue).
Parameters
| Name | In | Required | Notes |
|---|---|---|---|
id |
path | yes |
Responses
| Status | Meaning |
|---|---|
200 |
The attestation as the tool may see it, now revoked. |
401 |
connection_unauthorized or connection_expired. |
403 |
connection_revoke_not_allowed, or connection_paused while the owner has the tool paused. |
404 |
Not an attestation of this tool. |
POST /api/connections/{id}/permissions¶
Change what a tool is allowed (the owner)
Auth: Session
What the owner decides per connection, with the same fields as
authorizing it. A field left out stays as it is. allowVaultRead can
only be withdrawn here; true is refused with
connection_vault_reconnect, because granting it takes a connect the
tool asks for.
Parameters
| Name | In | Required | Notes |
|---|---|---|---|
id |
path | yes |
Request body
application/json
| Field | Type | Notes |
|---|---|---|
permissions |
array of string | As on authorize. |
section |
boolean | As on authorize. |
sections |
array of string | As on authorize. |
allowRevoke |
boolean | The tool may end what it proposed. |
allowHandOver |
boolean | The tool may receive the links its proposals became. |
allowVaultRead |
boolean | Only false: the tool stops reading the whole vault at once. |
Responses
| Status | Meaning |
|---|---|
200 |
The permissions as they now stand. |
400 |
connection_vault_reconnect, connection_permission_invalid, permission_escalation or vault_section_invalid. |
404 |
Not one of your connections. |
POST /api/connections/{id}/pause¶
Pause a tool (the owner)
Auth: Session
Refuses the tool's tokens with connection_paused, stops it connecting
another browser or adding links, and pauses its active links. Nothing
else changes, and its expiry keeps running.
Parameters
| Name | In | Required | Notes |
|---|---|---|---|
id |
path | yes |
Responses
| Status | Meaning |
|---|---|
200 |
{ "paused": true }. |
404 |
Not one of your connections. |
POST /api/connections/{id}/resume¶
Activate a paused tool (the owner)
Auth: Session
Lets the tool's tokens work again and restores the links the pause paused. A link the owner paused or changed themselves is left as it is.
Parameters
| Name | In | Required | Notes |
|---|---|---|---|
id |
path | yes |
Responses
| Status | Meaning |
|---|---|
200 |
{ "paused": false }. |
404 |
Not one of your connections. |
POST /api/connections/{id}/disconnect¶
Disconnect a tool (the owner)
Auth: Session
Deletes the connection and its tokens. With revokeLinks its links are
revoked. Otherwise they stay the owner's, and one paused by pausing the
tool stays paused.
Parameters
| Name | In | Required | Notes |
|---|---|---|---|
id |
path | yes |
Request body
application/json
| Field | Type | Notes |
|---|---|---|
revokeLinks |
boolean | Also revoke every link the tool proposed. |
Responses
| Status | Meaning |
|---|---|
204 |
Disconnected. |
404 |
Not one of your connections. |