Keep tokens safe
Practical habits for limiting what a token can do and rotating it without downtime.
A token acts as the organisation owner within its permissions. Treat it with care.
Use the least access
- Set each area to the lowest level the system needs. Most reporting jobs only need Read.
- Leave areas Disabled when they aren't used.
- Only turn on AI assistant access for tokens an assistant really needs. That setting has no effect on the REST API.
One token per system
Create a separate token for each system and name it clearly, for example "Payroll sync" or "BI dashboard". You can then disable one without breaking the rest, and the activity log tells you which system did what. You can have up to 20 tokens.
Expiry
A token expires 90 days after it is created by default. The longest you can set is one year. Put the expiry date in your calendar, or build a check that calls GET /me, which shows expires_at.
Rotate without downtime
Rotating a token invalidates the old secret straight away. To avoid an outage:
Create a second token
Make a new token with the same permissions.
Switch the system
Put the new secret into your system and confirm calls work.
Disable the old token
Disable it first so you can switch back if something breaks. Delete it when you're sure.
If a secret is exposed, rotate or disable the token straight away.
Storing secrets
- Keep tokens in your secrets manager or environment variables, never in source control.
- Never put a token in front end code or a mobile app.
- Imploy only stores a hash, so a lost secret can't be shown again. Rotate to get a new one.
Permissions
What each permission area covers.