Account and running it · Chapter 22

API tokens

With an API token a program can ask nexdiary something, a card on a dashboard such as nexdeck for instance. A token only reads, and never more than its account may read. Today it can do very little: it tells who you are and which version is running. It cannot get at your diary.

The operator switches it on

API tokens are off out of the box. The operator switches them on under “Settings”, tab “API”, with “Accounts may make API tokens”. If they switch them off again, every token answers with an error but stays, and works again as soon as they are switched back on. In the same card the operator sees every token with its owner, never the token itself, and can shut one down for good with “Block”. In the account it then reads “blocked by the operator”.

Making a token

1. Go to connections

   Through the round account button to “My account”, tab “Connections”, card “API tokens”.

2. “New token”

   Give it a name under “Name, so you know it again”, such as “nexdeck”.

3. “Runs out”

   “never” is preselected, otherwise “in 30 days”, “in 90 days” or “in a year”.

4. “Make”

   The token, starting with nxa_, is shown only now. Copy it into your program straight away; nexdiary keeps only a checksum. Below it, ready to copy, are the matching header and a curl call to try it.

An account can hold up to 20 tokens. The list shows when each was last used and when it runs out. A token you no longer need, you delete there.

What a token delivers today

Every request carries the token in the header Authorization: Bearer nxa_…, and the answers are JSON. There is exactly one route:

curl -H "Authorization: Bearer nxa_…" https://diary.example.com/api/v1/me

It returns name, display_name, level (always read) and the nexdiary version. There is nothing more under /api/v1 yet, and no way to read pages, notes or photos, or to write anything. What is there stays: new fields may come, nothing is renamed or taken away.

Limits and errors

• nexdiary refuses a request from a web page, that is one with an Origin header (403, origin_refused). The interface is for programs.
• With API tokens switched off you get 401 with api_off; with a wrong, expired, blocked or deleted token, 401 with token_invalid.
• More than 600 requests a minute with one token get 429 (slow_down), and Retry-After says when to go on.

The full description is in the project under docs/api.md.