Quickstart: a first call

Five minutes: get a token, ask the account service who it acts as, and list the account's domains. For signing people in to a product, start with tutorial.md instead.

1. Get a token

A person makes it, once, and it is shown once:

1. Sign in at https://accounts.praecise.com/account.
2. Under Service tokens, name the token (for example my-service, production) and press Mint.
3. Copy the value. It starts with prc_ and is stored only as a hash, so it cannot be shown again; revoke it there and mint another if it is lost.

A token acts as that one account and no other. A program cannot mint a token: that takes a signed-in person.

2. Make a first call

export PRAECISE_TOKEN=prc_…
curl -s https://accounts.praecise.com/api/me \
  -H "Authorization: Bearer $PRAECISE_TOKEN"

3. Read the answer

{ "account": { "id": "3b1f6c0e-…", "email": "you@example.com" } }

id is the account, a UUID that never changes. A 401 means the token was not accepted (mistyped, or revoked); every error is JSON with an error sentence and sometimes a detail.

4. Do something with it

List the account's domains and whether each is proven:

curl -s https://accounts.praecise.com/api/domains \
  -H "Authorization: Bearer $PRAECISE_TOKEN"

Claim a domain, then make a mailbox on it once it is verified:

curl -s https://accounts.praecise.com/api/domains \
  -H "Authorization: Bearer $PRAECISE_TOKEN" -H "Content-Type: application/json" \
  -d '{"domain": "example.com"}'

curl -s https://accounts.praecise.com/api/mailboxes \
  -H "Authorization: Bearer $PRAECISE_TOKEN" -H "Content-Type: application/json" \
  -d '{"localpart": "hello", "domain": "example.com", "name": "Hello", "kind": "human"}'

Every operation is in the OpenAPI document at https://accounts.praecise.com/openapi.json, and described in api.md.