API tokens

API tokens are keys that let other systems, such as an HR system, use the system’s REST API. A token acts as its user: that user’s permissions and region and project limits apply to everything the other system reads or writes.

From the side menu, open Settings › API tokens.

What’s on this screen

• Create token
• Search by token name and the filters User and Status (Active or Expired).
• The list of tokens. Without tokens it shows No API tokens yet.

Columns

• Name
• User: the user the token acts as.
• Abilities: what the token may do.
• Status: Active, Expired or User inactive.
• Last used: or Never.
• Expires: or No expiry.
• Created
• Revoke: the bin icon.

Fields

• User (required): an active user. Prefer a dedicated service user whose roles and limits are exactly what the other system may see.
• Name (required): up to 100 characters, for example HR system sync.
• Abilities (required, at least one):
  • read: read contracts, buildings, units, rooms, stays, payments, invoices, employees and projects.
  • write:employees: add and update employees, change their project and status.
  • write:projects: add and rename projects.
• Expires: leave empty for a token that does not expire. It stops working at the end of this day, which must be after today.

How to create a token

1. Click Create token.
2. Choose the User, type the Name, tick the Abilities and set Expires if needed.
3. Click Create.
4. The token appears once: Token “…” created. Click Copy token, keep it somewhere safe and give it to the other system, then click I copied it.

Caution

The token is shown only this once. If it is lost, revoke it and create a new one.

How to revoke a token

1. Click the bin icon on the token’s row.
2. Read Revoke token and confirm with Revoke. The token stops working at once and systems using it get 401 errors.

Note

You cannot manage the tokens of a user who has more access than you (You cannot manage API tokens of this user (they have more access than you).).

Required permission

API tokens › Manage.