Personal API tokens
Creating a token, what it can reach, and what invalidates it.
A personal API token is how you authenticate to the v1 API. Create one under Personal access tokens at Org settings → API & Webhooks.
This is the commonest reason somebody lands on this page, and the answer is that there is nothing to do: the extension mints its own credential when you press Sign in with Noots, and has done since long before this article was written. Tokens here are for code *you* write against the API. The extension appears under Connected apps, higher up the same screen.
- 1Open Org settings → API & Webhooks.
- 2Give the token a name - something that says which integration it's for, because that name is all you'll have to go on later.
- 3Create. The full token is shown once. Copy it now.
What a token looks like
It starts noots_ followed by 24 random bytes in URL-safe base64 - 38 characters in all. Send it as a bearer token:
Authorization: Bearer noots_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Only a SHA-256 hash of the token is stored. The list afterwards shows its name, the first few characters, when it was created and when it was last used - never the token. If you lose it, revoke it and make another; there is nothing to recover.
What a token can do
- It identifies one person in one organization - whichever organization you were in when you created it.
- Reads are scoped to what that person can see. A private project they're not on is invisible to their token, exactly as it is to them.
- Every token has the same reach. There is no way to mint a read-only one.
Every token is stored with ["read","write"] against it and nothing in Noots ever reads that value. It is a record of intent, not a permission. We're saying so rather than letting the field imply a control that doesn't exist.
Connected apps are a different list
Connected apps sits above the token list on the same screen and holds the Noots apps you have signed in to from a browser - today, that is the Chrome extension. Each one acts as you, with your permissions in this organization, and shows when it connected and when it was last used. There is one row per machine, so the extension on your laptop and the one on your desktop can be disconnected independently.
- Disconnect from that row revokes it immediately, and so does the extension's own Disconnect button.
- It is not behind a plan gate, deliberately, even though the token list is: the place you go to disconnect something must never be a place a downgrade can take away.
- Leaving the workspace revokes these along with everything else.
What kills a token
| Event | Effect |
|---|---|
| You revoke it | Dead immediately. You can only revoke your own tokens - there is no admin path here to revoke somebody else's. |
| The holder leaves the organization | Dead immediately. Removing a member revokes all their sessions and all their tokens for that organization, in the same step as the removal. |
| The holder is suspended, or their membership goes back to pending | Dead. Every request re-checks that the token's owner is an active member - it isn't a check done once at creation. |
| The account is deleted | Dead. |
You don't have to hunt for a leaver's integrations. Removing them from the workspace takes their tokens with them. That does mean an integration built on somebody's personal token stops the day they leave - so for anything the team depends on, use a token belonging to an account that isn't going anywhere.
API access is on the Team plan and above.