Skip to content

API

Everything the app does, this API does — it is the same surface, with no private endpoints held back. Operators run it under their own domain, so there is no shared base URL: substitute your own host throughout. To try it, use the official server, https://api.revoked.link. It is experimental and for testing, with no guarantees for your data.

Three common integrations

Goal Concrete example First implementation
Automate an existing workspace A scheduled job updates a now_playing record. An API key with vault permissions and access to a chosen section.
Build a service for other vault owners An emergency-card tool asks its user to share selected medical details. A proposal and connection approved in that user's app.
Add account sign-in to a website A shop signs a customer in and optionally asks for a delivery address. The Sign in with Revoked demo, then the start, callback and wait routes.

These credentials serve different purposes. A shop's sign-in token does not open the customer's vault. An API key for one workspace does not authenticate users of a website. A connection gives a tool the access its owner approved.

Terms used in the examples

Term Meaning Example
Server A Revoked installation with its own domain and accounts. https://api.example.com
Workspace The container for records, shares, requests and members. A company's workspace
Record One stored value or file. Key shipping_address, value Musterstraße 12, Berlin
Section A group of records; also used to limit a key's vault access. A Delivery section
Share A link through which selected records can be read. A delivery-address link sent to a shop
Request A form asking other people for information. A delivery-details request
Grant Permission to read selected current values until access ends. An approved address returned as a grant at sign-in

Example domains such as api.example.com are placeholders. $SERVER in shell examples is the Revoked server's origin, including https://, without a trailing slash. Credentials and IDs must come from that same server.

Where to start

If you want to Read
See every way in, side by side Ways to connect
Call the API from a script Authentication, then the reference
Call the API from JavaScript or TypeScript JavaScript SDK
Read or write vault data Records as a person, Vault as a key or tool
Consume a share someone sent you Shares
Collect data from other people Requests, then Callbacks
Hear about changes the moment they happen Webhooks
Build a tool that people share their data with Building a tool
Let an AI assistant organise your shares without seeing them MCP server
Let people sign in to your service with their Revoked account Sign in with Revoked
Check something a third party confirmed about a person, or confirm such things yourself Attestations
Verify who a share or request came from Trust chain
Generate a client openapi.yaml

Three things that will surprise you

Grants are living, not snapshots. A share resolves the record's current value each time it is read. Rotating a secret updates every share pointing at it, with no republish step — and revoking one takes effect on the next read, not the next sync. This is the whole point of the product, and it means you should not cache a resolve result any longer than you would cache the secret itself.

Public endpoints are protected by slug entropy alone. Anything under /api/public or /s is reachable by whoever holds the slug. Slugs are unguessable by construction and never derived from anything user-visible, and there is deliberately no endpoint that lists them. Treat a slug as the credential it is.

/s/{slug} content-negotiates. A request whose Accept header prefers text/html — which is to say, a browser — gets the share's viewer page, not data. Scripts should ask for a concrete format (.json, .csv, .vcf, .ics) or send an API-shaped Accept header, and can pass a gate password as ?password=.

Error handling

Failures come back in one envelope:

{ "code": "link_password_required", "message": "This link requires a password.", "status": 401 }

Key off code, never off message — the prose may be reworded, the code will not. Authorization failures name what was missing rather than returning a bare denial, so a 403 tells you which scope or grant you lack.

Every code and its message is listed in Error codes.

Error messages may echo values you sent, but never server-held state. That is deliberate: an error outlives the credential that produced it and ends up in logs, tickets and screenshots read by people who hold no key.

Encrypted links and saved keys describes the client-side formats, saved-share protection and explicit tool hand-over.