Account API
Three endpoints, one credential. A personal access token is generated in the console, shown once, and can be revoked at any time.
Authentication
Send `Authorization: Bearer <token>`. That is the only accepted form: no cookie fallback, no `?token=` query, no custom header. A token carries the permissions it was created with and never carries administrator authority.
Authorization: Bearer $ARAGON_TOKENEndpoints
/api/v1/meThe account behind this token, plus the token itself.
Scope: account:read
Request
- Authorization: Bearer <token>. The only credential this API accepts; cookies are ignored.
Response
200 with `user` (the same profile the account page shows), `token` (name, prefix, scopes, expiry, last use) and `server` (`{ name, api }`).
Example
curl -sS https://aragon.example/api/v1/me \
-H "Authorization: Bearer $ARAGON_TOKEN"Errors
- 401 E_UNAUTHENTICATED — No bearer token, or it is expired or revoked.
- 403 E_INSUFFICIENT_SCOPE — The token was not granted the scope below.
- 429 E_RATE_LIMITED — Over the per-token or per-account minute budget.
/api/v1/sessionsThe browser sessions signed in to this account.
Scope: sessions:read
Request
- Authorization: Bearer <token>. The only credential this API accepts; cookies are ignored.
Response
200 with `sessions[]`: `id`, `userAgent`, `createdAt`, `lastSeenAt`, `expiresAt`. No hashes, no epoch, no IP.
Example
curl -sS https://aragon.example/api/v1/sessions \
-H "Authorization: Bearer $ARAGON_TOKEN"Errors
- 401 E_UNAUTHENTICATED — No bearer token, or it is expired or revoked.
- 403 E_INSUFFICIENT_SCOPE — The token was not granted the scope below.
- 429 E_RATE_LIMITED — Over the per-token or per-account minute budget.
/api/v1/sessions/{id}Sign one of your sessions out.
Scope: sessions:revoke
Request
- Authorization: Bearer <token>. The only credential this API accepts; cookies are ignored.
- id (path): The session id from the list.
Response
204 with no body. The row keeps `revoked_at`; the browser is signed out at once.
Example
curl -sS -X DELETE https://aragon.example/api/v1/sessions/SESSION_ID \
-H "Authorization: Bearer $ARAGON_TOKEN"Errors
- 401 E_UNAUTHENTICATED — No bearer token, or it is expired or revoked.
- 403 E_INSUFFICIENT_SCOPE — The token was not granted the scope below.
- 429 E_RATE_LIMITED — Over the per-token or per-account minute budget.
- 404 E_NOT_FOUND — No such session, or it belongs to somebody else (the two are not distinguished).
Error shapes
| Shape | Where it is used |
|---|---|
{"error":{"code":"E_UNAUTHENTICATED","message":"…"}} | Every `/api/v1` and `/api/account` response. The HTTP status carries the class. |
{"error":"authorization_pending","error_description":"…"} | The two device endpoints only: the RFC 8628 / RFC 6749 shape every OAuth client branches on. |
Device authorisation
This is how the CLI and the desktop app get a token without a callback URL: RFC 8628, two public POSTs and one page a human visits. The protocol is live today; the `aragon login` subcommand that drives it ships in the next release.
1. Ask for a code
Your client posts its id and the permissions it wants. Nothing is authorised yet.
curl -sS -X POST https://aragon.example/api/device/code \ -H "content-type: application/json" \ -d '{"client_id":"aragon-cli","scope":"account:read"}'2. A human approves it
Print `user_code` and `verification_uri_complete`. The person opens the link, signs in, and approves — on any device, including a phone.
Open https://aragon.example/activate?code=BCDF-GHJK3. Poll until it is answered
Poll every `interval` seconds. `authorization_pending` means keep waiting, `slow_down` means wait the new interval, `access_denied` and `expired_token` mean stop. The token comes back exactly once, in the response to the poll that succeeds.
curl -sS -X POST https://aragon.example/api/device/token \ -H "content-type: application/json" \ -d '{"grant_type":"urn:ietf:params:oauth:grant-type:device_code", "device_code":"DEVICE_CODE","client_id":"aragon-cli"}'
The `/activate` page needs no JavaScript, and neither does approving: the two buttons are a plain form post.
Cross-origin requests are not allowed
These endpoints are for servers and terminals. There is deliberately no `Access-Control-Allow-Origin` header, so a browser `fetch` from another origin fails at the preflight — that is the design, not a bug (D-56). If you are writing a browser app, talk to your own server and keep the token there.
Honest limits
- A token is not an administrator: no endpoint here can change an account, a role or a password.
- Changing your password revokes every token immediately (they share the session epoch).
- Tokens are stored as a hash. If you lose one, create a new one — it cannot be recovered or revealed again.
- There is no IP binding, no per-endpoint scope split and no rotation API; revoke and create.
- The token format is `aragon_pat_<prefix>_<secret>`; the prefix is public and appears in the console and the audit log.
- Creating a token needs JavaScript: the value can only exist in the response that creates it, and a redirect cannot carry it. Listing, revoking and approving a device all work without it.
- The device flow does not remember a device. Each machine is approved once and receives an ordinary token; remembering one would need a second credential type.
- The eight-character user code is stored as typed, because a human has to read it off one screen and type it into another. A fifteen-minute life, a 20-symbol alphabet, two independent rate limits and single use pay for that.