Skip to main content
Every API token is attached to a role when you create it. The token gets exactly the rights of that role, in the workspace where it was created.
  • You choose the role in the Role field when you create the token in Settings › Developer › API Tokens. See API tokens.
  • Rights are edited on the role, in Settings › Role. Changing a role immediately changes what every token attached to it can do. See Role permissions.
  • A token has no permission list of its own and no expiry date. To restrict a token, attach it to a role with fewer rights.

​
What a token can do

A token can do exactly what its role can do: read an object when the role has Read on it, create or update it when the role has Write, delete it when the role has Delete. All endpoints also require a valid token (otherwise 401), and only return data from the token’s workspace.

​
403 response

When the role lacks the required right, the API returns 403 Forbidden and does not change any data:
The text after Requires names the missing right. Give that right to the token’s role, or use a token attached to another role.

​
Recommendations

  • Create a dedicated role for each integration (for example “ERP sync”) with only the objects it writes to.
  • Use one token per integration and environment, so you can revoke one without affecting the others.
  • For read-only integrations, use a role with Read rights only.
See also Authentication and Error handling.
Last modified on October 27, 2026