Authentication
Every call on /v1 takes a bearer token.
curl https://api.heyclave.com/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.
Try without an account
An agent can start an account with no sign-in and no email to wait for.
| Call | What it does |
|---|---|
POST /v1/auth/try |
makes an account to try Clave, and answers with its token |
Send {}, or {"email": "..."} to say where the verification link goes
later. Clave does not check the address now and sends it no mail. The
answer is 201 with token, writes_until, limits and next_action.
This account makes drafts only. It can make changes for 6 hours and for 5
builds. Its forms keep each message and send no mail. It cannot invite
people, give a site away, take payments or add a domain. After that, each
change gets verify_email_required. To keep the work, the owner verifies
an email:
| Call | What it does |
|---|---|
POST /v1/account/verify |
mails the owner a link that keeps the work |
Send {"email": "..."}, or {} to use the address from the start. The
answer is 200 with email and hint. Show the owner the hint: the
email shows the same code. When the owner opens the link and presses the
button, the account is a normal Clave account, with the same token.
The answer is the same when another account uses the address, and then no mail goes. If no mail arrives, try another address.
When too many people try at the same time, the answer is platform_full.
Sign in or make an account instead.
A short token from the connector
An agent on the connector can get a token without a
second sign-in. The MCP tool create_api_token gives a one-time code,
and this call exchanges it.
| Call | What it does |
|---|---|
POST /v1/token-exchange |
exchanges a code for a token that works for 10 minutes |
Send {"code": "..."} with no bearer token. The answer is {"token", "expires_at"}. A code works one time, for 60 seconds. A used, expired or
unknown code gets a 400 with the code invalid_code.
The code is in the chat, and the token is not: the agent runs the exchange in a shell and keeps the token in a variable.
What a bad token gets
A missing or revoked token gets a 401 with the ordinary error body. Read Errors.