> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qwoty.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Permissions

> How an API token's role decides which endpoints it can call.

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.

```text theme={null}
API token  →  role (admin, manager, sale, view_only or a custom role)  →  rights per object (Read, Write, Delete…)
```

* You choose the role in the **Role** field when you create the token in **Settings › Developer › API Tokens**. See [API tokens](https://docs.qwoty.io/user-guide/settings/developer/api-tokens.md).
* 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](https://docs.qwoty.io/user-guide/settings/users/reference/permissions.md).
* 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**.

| Endpoints | Role setting | Right name in errors |
| - | - | - |
| [Customers](https://docs.qwoty.io/api-reference/customers/create.md), [contacts](https://docs.qwoty.io/api-reference/contacts/create.md), [addresses](https://docs.qwoty.io/api-reference/addresses/create.md) | **Customers** | `customer:write` |
| [Catalogs](https://docs.qwoty.io/api-reference/catalogs/create.md), [categories](https://docs.qwoty.io/api-reference/categories/create.md), [prices](https://docs.qwoty.io/api-reference/prices/list.md), [products](https://docs.qwoty.io/api-reference/products/create.md), [product parents](https://docs.qwoty.io/api-reference/product-parents/create.md), [payment terms](https://docs.qwoty.io/api-reference/payment-terms/create.md) | **Products & Pricing** | `product_pricing:write` |

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:

```json theme={null}
{
  "error": "Insufficient permissions. Requires customer:write"
}
```

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](https://docs.qwoty.io/developers/authentication.md) and [Error handling](https://docs.qwoty.io/developers/core-concepts/error-handling.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.