Authentication
API tokens are part of the Custom plan — everything the Team plan has, plus these. Nothing on sale includes them, which is what makes that tier a "Book a call" rather than a checkout; see the pricing page.
Once a team has them, create a token in Team settings → API tokens. It is shown once.
Authorization: Bearer npat_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Every request needs one. A request without a usable token is refused 401 before anything else is
looked at, and a token is the only credential these endpoints accept — a session cookie from the
app will not do, and neither will any other kind of bearer token.
What a token is
A token belongs to the person who created it and is pinned to one team. It can never do more than that person can: if they lose access to something, so does the token, on the very next request. Nothing has to go and revoke it.
That "no more than that person can" is decided per document. Somebody who can open every script in
their team reads every one of them through their token; somebody held to a handful gets those and a
404 for the rest, and the answer changes the moment their access does. So a token that stops
returning a document has not broken — check what its owner can do with that document.
Two scopes read and one writes. A token without plugin:write changes nothing, and nothing
else implies it.
| Scope | What it allows |
|---|---|
team:read |
Reading the team, its folders, which documents are in them, and its plug-ins |
document:read |
Reading documents and their saved versions, as JSON, and exported files |
plugin:write |
Uploading, enabling, disabling and removing the team's plug-ins |
plugin:write is still no more than its holder: only a team admin can manage plug-ins, so a
member's token carrying it is refused all the same, and only on a team with custom plug-ins. It
reads nothing either — pair it with team:read to list what the team has.
Each endpoint names the scope it needs in the reference. A token missing that scope is
refused 403, in words that say which scope was wanted.
One endpoint names none. /api/v1/templates is the component library — the same for every team,
derived from a file that ships with the app, and holding nothing any team owns — so there is
nothing there to authorize against. It still needs a token, so that one credential opens the whole
of /api/v1.
A public document owned by another team is refused too, even though anyone can open it in a browser. A token is a key to one team, not a browser.
Trying it here
The reference runs requests against your own team from your own browser. Paste a token into its auth panel and any endpoint on the page becomes something you can execute and read the real answer to.
Two things worth knowing about how that works:
- Your token is not stored. It lives as long as the browser tab does and is never written to local storage.
- Your token goes to
app.nodepen.ioand nowhere else. The request is made by your browser directly against the API — it does not pass through this docs site, and it does not pass through any third-party proxy.
A token pasted here is still a real credential. Prefer one minted for the purpose, and revoke it when you are done.
Revoking
Revoking deletes the token. There is no expiry to wait for and no grace period: the next request
carrying it is refused 401, in the same words as a request carrying nothing at all.
You can hold 20 tokens for a team. Revoke one to make room.