Creating and managing API tokens

An API token lets third-party software (payroll, directory, scheduling, data warehouse) read or write your Illizeo data through the public API, within the scopes you grant it. This article explains how to create a token, hand it over, edit it, regenerate it, suspend it and revoke it. It is for the administrators of your space.

Before you start #

• The screen is under Settings › Manage Illizeo › API Tokens. The entry only appears if your subscription includes API access (it is open during the trial period) and if one of your roles holds the “API tokens — View” permission.
• Creating, editing, regenerating, deactivating or revoking a token also requires the “API tokens — Create / edit / revoke” permission at the Execute level. Without it, the list and the token pages can be read, but no action button appears.
• By default, only the Administrator role holds these two permissions. They are set in Settings › Manage Employees › Employee Roles (see Permissions & roles).

A token acts on behalf of its creator #

A token has no permissions of its own: it inherits the permissions and the perimeter of the person who created it, never more. A call that reads employees only sees the employees that person sees in the application; a write requires the same permission as the equivalent action on screen. The scopes ticked on the token come on top of this: they limit what the token may call.

• If the creator’s permissions change, the token’s change with them, from the next call.
• If the creator’s account is no longer active (departure, suspension), the token stops working.
• Another administrator may edit or regenerate the token: it still acts on behalf of its creator.

So create each token with an account whose permissions match what the integration needs to see.

The token list #

The page first shows the API platform card, which summarises usage for the period (see Monitoring and troubleshooting an API token), then the table of tokens:

• Name, with the creation date and its author;
• Token: only the beginning of the value, followed by asterisks;
• Scopes: the first three, the others when hovering over the “+n” badge; write scopes are coloured;
• Created by, Last used (with the expiry date), Status and Actions.

The Search field filters by name. The Documentation button opens the API documentation, described in Public API: developer guide.

Creating a token #

1. Click New token (or Create the first token if the list is empty).
2. Name (required, 100 characters at most): name the system that will use the token, for example “Payroll sync”. This is how you will recognise it in the usage log. Two tokens that are not revoked cannot share a name; the screen tells you as you type.
3. Expiry (optional): pick a date; the token stops working at the end of that day. Left empty, it never expires.
4. Rate limit (requests / minute): from 1 to 10,000. Left empty, the token gets the default limit shown under the field (60 requests per minute).
5. Scopes (at least one): tick Read and/or Write, resource by resource.
6. Click Create token.

Resources are arranged in two groups, Data and Referential. In each group, All read ticks every read scope and Clear unticks the whole group. Only the resources of the modules enabled in your space are offered: Scheduling, Annualised working time, Budget, BDESE, Swiss payroll or Flex Office only appear if the module is enabled. What each scope opens is detailed in the developer guide.

Copying the token, once #

Once the token is created, the Your API token window shows its full value (it starts with illz_) and an example call. Copy the value with the copy button, send it through a secure channel to the person configuring the integration, then click I have saved it.

This value is never shown again: Illizeo only keeps a fingerprint of it. If it is lost, regenerate the token.

Editing a token #

The Edit icon in the list, or the Edit button on the token page, opens the Edit API token page. You can change the name, expiry, rate limit and scopes there, then click Save. Changes apply from the next call; the token value itself does not change.

Regenerating a token #

The Regenerate token button, on the token page or the edit page, asks for confirmation and then issues a new value. The old one stops working immediately; scopes, expiry and rate limit are kept. The new value is shown only once, in the Your new token window: update the integration straight away.

Deactivating or revoking #

• Deactivate: the switch in the Status column suspends the token, whose calls are then refused. Switch it back to reactivate it. This is the right move to cut off an integration while you check something.
• Revoke: the Revoke icon opens the Revoke API token confirmation. Revocation is final: every integration using the token loses access immediately. The token stays in the list with the Revoked status, for the record; it can no longer be edited, regenerated or reactivated. Its name becomes available again for a new token.

Good to know #

• A token whose expiry date has passed shows the Expired status and its calls are refused; every night, Illizeo also switches it to inactive. To bring it back into service, edit it with a new expiry date (or none), save, then reactivate it in the list if it shows as inactive.
• Token creations, edits, manual activations and deactivations, regenerations and revocations are recorded in Settings › Manage Illizeo › User Logs. A token value never appears there, only the fact that it changed.
• A link from a module’s integrations page may open this form with a name and scopes already suggested. Nothing is created until you click Create token.
• If your subscription does not include API access, the page says so and offers See plans.

FAQ #

I cannot see the “New token” button. #

It requires the “API tokens — Create / edit / revoke” permission at the Execute level.

I have lost a token value. #

It cannot be shown again. Regenerate the token and send the new value to the integration.

Should I use one token per integration? #

It is better: each token has its own name, scopes, limit and usage log, and can be revoked without cutting off the other integrations.