Authentication
Every call on /v1 takes a bearer token.
curl https://api.heyclave.party/v1/account \
-H "Authorization: Bearer $CLAVE_API_TOKEN"
A token starts with clave_. Read Get a token for how to
mint one.
Every token is a full-account token
A token carries the authority of its account. That includes the sites other owners shared with the account, which is the same model and not a wider one.
Scoped tokens do not exist. Three presets were designed and not built: a scope column with one legal value is an unused field waiting to rot. Named, listed and revocable was the part worth having.
The consequence worth knowing: an owner cannot see or revoke a collaborator's tokens. Removing the collaboration is what ends the access.
Sign in from an agent
An agent can start a sign-in itself, and the person finishes it in their inbox.
| Call | What it does |
|---|---|
POST /v1/auth/start |
asks Clave to mail an access request to an address |
POST /v1/auth/redeem |
exchanges an approved request for a token |
The person opens the link and approves on a page in the browser. That page shows a word pair, and the agent shows the same pair, so the person can check they are approving the request in front of them.
Clave mints the token only after the approval.
What a bad token gets
A missing or revoked token gets a 401 with the ordinary error body. Read Errors.