# Authentication

Every call on `/v1` takes a bearer token.

```sh
curl https://api.heyclave.party/v1/account \
  -H "Authorization: Bearer $CLAVE_API_TOKEN"
```

A token starts with `clave_`. Read [Get a token](/start/tokens) 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](/api/errors).

---

## Where this page sits

This is one page of the Clave documentation.
Read it as a web page at https://docs.heyclave.party/api/auth.
Every page has a `.md` address, and https://docs.heyclave.party/llms.txt lists them all.

- Previous: [The terminal client](https://docs.heyclave.party/agents/terminal.md)
- Next: [Errors](https://docs.heyclave.party/api/errors.md)
- Index: [Overview](https://docs.heyclave.party/index.md)