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 never reads the vault 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. |
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 or connection_challenge_invalid. |
409 |
connection_not_connected: reuse was set, but the tool is not connected or its connection has lapsed. |
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 the tool's links
Auth: Connection
The links the tool's proposals became — status, views, expiry. url
appears only on links the owner handed to the tool, and only while they
can be opened. 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. |
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 revoke its links. |
allowHandOver |
boolean | Whether the owner lets the tool receive links. |
links |
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. |
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. Only when the owner allowed it
(allowRevoke); a tool can end a share, never start one or read it.
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. |
404 |
Not a link of this tool. |
POST /api/connections/{id}/permissions¶
Change what a tool is allowed (the owner)
Auth: Session
The two things the owner decides per connection. A field left out stays as it is.
Parameters
| Name | In | Required | Notes |
|---|---|---|---|
id |
path | yes |
Request body
application/json
| Field | Type | Notes |
|---|---|---|
allowRevoke |
boolean | The tool may revoke the links its proposals became. |
allowHandOver |
boolean | The tool may receive the links its proposals became. |
Responses
| Status | Meaning |
|---|---|
200 |
Both permissions as they now stand. |
404 |
Not one of your connections. |