On this page0
Guide
Create an API token
Give a script or integration its own key to the Zonitix API, limited to exactly the permissions it needs, with an end date.
Before you start
- This is an IT task. It assumes you have a script or integration that calls the Zonitix API and that you know where that script keeps its secrets. If you only use Zonitix through its screens you do not need a token; hand this page to the person who writes or runs the script.
- A role with the permission to create personal API tokens (“create_api_tokens”; search for that name in Access Control). Only administrators have it out of the box, as no other built-in role includes it, so add it to a role for anyone else who needs tokens.
- If your organization requires MFA for you, MFA must be set up on your account and you must have signed in with it.
- Your password or passkey to hand. Creating a token asks you to confirm it’s you.
- A safe place to keep the token, such as your password or secrets manager.
Create the token
Step 1: Open API Tokens
Go to SystemAPI Tokens and click “New token”.
Step 2: Name it and set the expiry
Enter a “Token name” that says what it is for, such as the script that will use it. Choose “Expires in”: 7, 30, 60, 90 or 180 days, or 1 year. The default is 90 days. No token lasts longer than a year.
Step 3: Pick its permissions
Under “Permissions”, tick only what the integration needs. The list shows only permissions you hold yourself, grouped by area, and “Filter permissions” helps you find one. You must tick at least one.
The permission to create tokens is never on the list, so a token cannot make more tokens.
Step 4: Confirm it's you
Click “Create token”. If you have not confirmed recently, a “Sudo Mode Required” box asks for your password or passkey. After you confirm, the token is created.
Step 5: Copy it now
The “Copy your API token” screen shows the token once. Click “Copy to clipboard” and store it straight away. Zonitix keeps only a scrambled fingerprint of it, so nobody, including Zonitix, can show it to you again. Click “I’VE COPIED IT” to close.
Your developer sends it in the “Authorization” header as a Bearer token. The “API reference” button at the top of the page opens the full API documentation.
Replace or revoke a token
Step 6: Revoke
In the list, click “Revoke” on the token and confirm with “Revoke token”. It stops working within a second, and anything still using it is refused.
Step 7: Rotate
There is no rotate button. To rotate, create a new token, switch the integration over to it, then revoke the old one. Do the same if a token is lost or may have leaked.
Step 8: Oversee everyone's tokens
People who manage security settings also see “All tokens (admin)”, which lists every token in your organization with its owner, and can revoke any of them. Nobody can see a token’s value there.
What a token cannot do
Step 9: The limits
- It never carries the administrator role. Even an administrator’s token can do only the permissions ticked on it, and admin-only actions are out of reach.
- Actions that ask you to confirm it’s you (Sudo Mode) cannot be done with a token.
- It cannot create, list or revoke tokens.
- It stops working when it expires, when it is revoked, when your account is blocked or offboarded, after your password is changed, set by an administrator or expires, and if MFA is required for you but you have no MFA set up. Each case is listed under What Ends A Token.
What you should see
The token appears in the list with a green “Active” label, the first few characters of the token, when it was created, when it expires, when it was last used and from where, and its permissions. Creating and revoking tokens is recorded in the audit log.
If something goes wrong
- "Your account must have multi-factor authentication set up and verified before you can create API tokens."
- MFA is required for you. Set up MFA, sign out, sign back in with it, then try again.
- "You already have 20 active API tokens — revoke an unused one first."
- Each person can hold up to 20 active tokens. Revoke ones you no longer use.
- A script that worked suddenly gets 401 errors.
- The token expired, was revoked, or was cut off because the owner signed out everywhere, changed their password or left. Check its status in the list and create a new one if needed.
- A token works for some things but is refused for others.
- It only has the permissions ticked on it, limited to what its owner still holds. Admin-only and Sudo Mode actions are never allowed. Create a new token with the right permissions.
Still stuck? See When something goes wrong, or Contact Zonitix support.