The app step by step · Chapter 33

API tokens for programs

With an API token, programs such as n8n, a card in nexdeck or a script of your own fetch notes, tasks and numbers from nexlore and, if you allow it, write into it as well. You don't need any AI for that, and the tokens have nothing to do with the MCP keys from the chapter AI. What a token can do and why it is built this way is on the page AI, MCP and API.

The operator switches the API on

API tokens are off by default. If you are the operator, you open Settings from the account menu behind your profile picture at the top right, go to Server and there to AI, API and plugins. On the card “API tokens” you switch on Accounts may make API tokens. While that switch is off, the card in the account says the operator hasn't switched API tokens on, and no token can be made.

Making a token

Open My account and there the Connections tab. The card “API tokens” is right at the top, and New token makes one.

1. Name

   Give the token a name you'll know it by later, such as “n8n at home” or “Dashboard”.

2. Level

   Read fetches spaces, notes, search results, tasks and numbers and changes nothing. Write also makes and changes notes, appends to them, writes into the daily note and the inbox and ticks tasks off. Pick the smallest level your program needs.

3. Spaces

   Choose “All spaces I may read, later ones too” or “Only these”, and then tick the spaces the program should see.

4. Runs out

   A token runs out in 30 days, in 90 days, in a year or never. “Never” is chosen by default.

5. Make

   After Make, nexlore shows the token, which starts with nxa_, exactly once. Below it you'll find a ready-made header for n8n and a command to try it, each with a button to copy. Copy the token into your program now, because nexlore only keeps a checksum of it.

Account

Putting the token into n8n

In n8n you talk to nexlore with the HTTP Request node. You set up the sign-in once as a credential and then reuse it for every node.

1. Pick the sign-in

   In the node, set Authentication to “Generic Credential Type” and Generic Auth Type to “Header Auth”.

2. Add the header

   Make a new credential with the Name Authorization and the Value Bearer, a space and then your token.

3. Enter the address

   As the URL you take your nexlore's address with /api/v1 and the route after it, for example https://notes.example.com/api/v1/dashboard. To write, set the method to POST and send the body as JSON.

Generic Auth Type  Header Auth
Name               Authorization
Value              Bearer nxa_...

{"text": "[ ] pick up the parcel"}

The example writes a thought at the top of the inbox of your main space, with the time after it. Because the line starts with [ ], it becomes a real task. In the same way a workflow can write something into the daily note every morning (POST /api/v1/daily) or gather tasks from another tool into nexlore.

Trying it with curl

Before you build a whole workflow, the quickest way to check the token is a shell. /api/v1/me names the token's account, level and spaces, and /api/v1/dashboard returns the numbers for a dashboard.

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

curl https://notes.example.com/api/v1/dashboard \
  -H "Authorization: Bearer nxa_..."

If you get 401 with api_off, the operator has switched API tokens off. With token_invalid the token is wrong, has run out or was blocked. A 403 with origin_refused means a browser sent the request. nexlore doesn't allow that, because the API is meant for programs and not for web pages.

A card on your dashboard

A dashboard card such as the one for nexdeck shows you the numbers of your notes, the tasks that are due or overdue and the notes changed last. A token with the level Read is enough for that. If you want to tick tasks off or quickly write into the inbox from the card, the token needs Write. In the card you enter your nexlore's address and the token, and that's all it needs. Which requests such a card makes is described in docs/api.md in nexlore's repository, in the section “A dashboard card”.

What a token leaves in your notes

Every change through a token becomes a version of the note with the source “Program (API)”, with your account as its author. So in the Versions tab next to the note you see exactly what a program wrote, and you can bring back the state before it if you need to. A token can never delete, move, rename or share. If a note has changed since the program read it, or someone is editing it right now, the new text lands in a conflict copy next to it.

When a token runs out

A week before a token runs out, its entry in the list turns yellow and you get the notification “API tokens run out”, once per token. That occasion is on by default, and you can switch it off under My account, Notifications. Once the token has run out, it says “ran out on …”, and every request with it gets 401 with token_invalid. Make a new token then and swap it in your program.

Deleting and blocking

As the operator, you see every token on the server on the card “API tokens” under AI, API and plugins, with its account, level, spaces and when it was last used. Not even you see the token itself, because nexlore never stored it anywhere.