Skip to content

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.