---
title: Creating and managing API tokens
description: "Create a token for third-party software, choose its scopes, expiry and limit, then edit, regenerate, deactivate or revoke it."
url: "https://illizeo.com/en/centre-aide/api-managing-tokens/"
updated: "2026-11-05"
category: Platform / REST API
---

# 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](https://illizeo.com/en/docs-category/platform-en/platform-roles-permissions/)).

## 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](https://illizeo.com/en/centre-aide/api-monitoring-and-troubleshooting-a-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](https://illizeo.com/en/centre-aide/api-developer-guide/).

![The Settings, Manage Illizeo, API Tokens page of a workspace with no token yet: at the top the API platform card with the period's usage, then the API Tokens block with the Search, Documentation and New token buttons, and the No API token yet empty state with the Create the first token button](https://i0.wp.com/illizeo.com/wp-content/uploads/2026/11/api-managing-tokens-01.en_.png?resize=800%2C500&quality=80&ssl=1)
Settings › Manage Illizeo › API Tokens.

## 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**.

![The New API token form: box reminding that the token acts on behalf of its creator, Name field filled with Payroll sync, Expiry (optional) and Rate limit (requests / minute) fields with the help text on limits, then the beginning of the scope list](https://i0.wp.com/illizeo.com/wp-content/uploads/2026/11/api-managing-tokens-02.en_.png?resize=800%2C500&quality=80&ssl=1)
The token creation form.

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.

![The Data group of the scope picker after All read: one row per resource (Employees, Absences, Time and attendance, Scheduling, Documents, Payroll…), the read box ticked, the write box empty, and a dash where that access does not exist for the resource](https://i0.wp.com/illizeo.com/wp-content/uploads/2026/11/api-managing-tokens-03.en_.png?resize=800%2C523&quality=80&ssl=1)
A token's scopes, Data group, after “All read”.

## 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.

![The Revoke API token confirmation box: question with the token name, warning that the action is final and that every integration loses access immediately, Cancel and Revoke buttons](https://i0.wp.com/illizeo.com/wp-content/uploads/2026/11/api-managing-tokens-04.en_.png?resize=448%2C356&quality=80&ssl=1)
The revocation confirmation.

## 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.

### *Similaire*