Skip to content

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_TOKEN

Endpoints

GET/api/v1/me

The 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.
GET/api/v1/sessions

The 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.
DELETE/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

The two error envelopes this API speaks
ShapeWhere 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. 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. 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-GHJK
  3. 3. 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

Create a token · All documents