Personal tokens that let a script or tool call the API as you, with only the access you give it.
What an API token is
An API token lets a script, a scheduled job or another tool call the API as you, without your API key. You make one on the API Tokens page, which opens from Token Manager in your profile menu.
A token acts as you, and it can never do more than you can. With Same access as my account, it can do anything you can do, on every project you can reach. With Limited access, it can reach only the projects you pick, and do only what you allow there. Either way its access follows yours, so a permission you lose is lost by your tokens too.
The page lists only the tokens you created, and nobody else can delete them.
Give each tool its own token, with only the access it needs. Then you can cut off one tool without touching the others, and you never hand out your API key.
Use Cases
Give a tool its own access to the API
Let a script or an integration call the API with only the access it needs.
- Open your profile menu at the top right, pick Token Manager, and click Create token.
- In Basics, give the token a Purpose that says what it is for, such as the tool's name. Leave Reusable on so the tool can use it for more than one call, and choose an Expiration.
- Click Next. In Access, pick Limited access and tick each project the tool works with.
- Click Next. In Permissions, tick what the token may create, read, update and delete in each feature. A box you cannot tick is a permission you do not hold on every project you picked.
- Click Create token. Copy the token with the copy button next to it, then click Done.
- In the tool, send the token with each request, either as the
auth_tokenparameter or in acountly-tokenheader.
Hand out a token that expires
Give access for a short time, or for exactly one call, so a token that gets lost or forgotten does not stay useful.
- Open Token Manager from your profile menu and click Create token.
- Give the token a Purpose.
- For exactly one call, turn Reusable off. The token works for a single API call and is used up.
- For a time limit, pick Expires after under Expiration and enter a number of hours, days or months. A month counts as 30 days.
- Finish Access, and Permissions for a limited token, then click Create token and copy the token.
When its time runs out, the token stops working. The list shows it as Expired for up to a day, and then it disappears on its own.
Revoke a token
Cut off a tool's access, because the tool is retired or its token may have leaked.
- Open Token Manager from your profile menu.
- Type part of the token's purpose in the search box to find it.
- Open the menu (⋮) at the end of its row and pick Delete.
- Confirm with Delete token.
Anything using the token stops working at once, and a deleted token cannot be brought back. If the tool still needs access, create its new token first and switch the tool over before you delete the old one.
FAQs
Where is my API key?
At the top of your profile menu, with a copy button. A token is the safer thing to give a tool, because you can limit it, let it expire and delete it without changing your key.
Can I copy a token again after I close the form?
Yes. Use the copy button in the Token column, or Copy token in the row's menu.
Can I change a token's projects, permissions or expiry?
No. Create a new token with the settings you want, switch the tool over to it, and delete the old one.
Why can't I tick a permission for a limited token?
You do not hold that permission on every project you picked. Pick fewer projects, or ask an admin to give you the permission.
Why is there no sign-in option on my limited token?
Only a token with Same access as my account can be allowed to sign in to the dashboard. A limited token never can.
What happens to my tokens when my own access changes?
They follow it. A token cannot do more than you can, so a permission or project you lose is lost by your tokens as well.
Why can't I see a colleague's tokens?
The page lists only the tokens you created. Everyone manages their own.