API Key Permissions: Which Role to Assign

API key permissions define what an application is allowed to do in Chatterfy. They depend on two service account roles: the company role and the role in each Space. This article explains which role to

Updated November 2, 20265 min

API key permissions define what an application is allowed to do in Chatterfy. They depend on two service account roles: the company role and the role in each Space.

This article explains which role to choose for your task, what permissions API methods require, and why the API sometimes responds with "access denied" or "not found".

How API key permissions work

A key is a service account's pass. Two roles determine what exactly the pass opens:

Company role — permissions at the company level: view the company and its members, work with Tracker;

Role in space — permissions for bots and chats in a specific Space. Each Space can have its own role.

If the service account is not in the Space, the bots and chats of that Space do not exist for the API. How to add an account to a Space is explained in the article How to get an API key.

Which role to choose in Space for integration

What the integration does	Role in Space
Only reads chats and messages	Space viewer
Reads, replies, changes statuses and tags, exports chats	Space controller
Everything above, plus analytics, creating and deleting tags, deleting chats, bot settings	Space manager
Everything above, plus managing the Space itself and its members	Space administrator

Choose the most restricted role that is sufficient for your task. If the key falls into the wrong hands, the damage will be less.

Space operator and Space hidden operator are not suitable for integrations

Usually, these roles only see chats assigned to this member — it depends on how chats are distributed in the bot. In that case, chat lists will be returned empty, and a request to another chat will return 403.

Which role to choose in the company for integration

What the integration does	Role in the company
Works with bots, chats, messages, and analytics	Operator. Rights for bots will come from the role in Space
Works with Tracker: campaigns, domains, landing pages, leads	Administrator. Buyer and Buyer team lead only see campaigns where they are listed as the buyer
Receives a full list of company members	Owner or Administrator

You can also assign your own role. How to build a role from the necessary rights — in the article Custom roles — company and space permissions.

Rights for working with chats and messages

API key rights for bots, chats, and messages. The names of the rights match the keys in the access field — they are used to debug 403 errors and build your own role:

What the integration does	Right	In which roles it is available
Sees bots, their tags, and fields	`bot.read`	In all Space roles
Reads chats	`chat.read`	In all Space roles
Reads messages	`message.read`	In all Space roles
Sees customer names and usernames	`chat.contacts.read`	In all Space roles, except Space hidden operator
Sends messages	`message.send`	Space controller and higher
Changes status, tags, assignee, and chat fields	`chat.manage`	Space controller and higher
Exports chats	`chat.export`	Space controller and higher
Edits and deletes messages	`message.manage`, `message.delete`	Space moderator, Space controller and higher

Permissions for analytics, bot settings, Space and Tracker

API key permissions for analytics, tags and bot settings, deleting chats, Space and Tracker members:

What the integration does	Permission	Included in roles
Views bot analytics	`analytics.bot.read`	Space manager and higher
Creates and deletes bot tags	`bot.settings.manage`	Space manager and higher
Changes bot name, status, and description	`bot.manage`	Space manager and above
Deletes chats	`chat.delete`	Space manager and above
Views Space members	`space.read`	In all Space roles
Works with Tracker campaigns and leads	`campaign.read`, `campaign.manage`	Administrator; Buyer and Buyer team lead — own only
Works with domains and landing pages	`domain.read`, `domain.manage`, `landing.read`	Administrator; Buyer and Buyer team lead — own only

How to check key permissions via the access field

Companies, Spaces, and bots are returned in API responses with an access field — these are the service account's permissions for this object. For example, here is what a bot with the Space controller role looks like (some fields are hidden):

{
  "id": "0b7c2e64-5d1f-4a8e-9c3b-2f6d8e1a4b90",
  "name": "Sales bot",
  "status": "active",
  "access": {
    "bot.read": "all",
    "chat.read": "all",
    "chat.manage": "all",
    "chat.export": "all",
    "message.read": "all",
    "message.send": "all"
  }
}

The account does not have any permissions not listed here. The value next to the permission represents its scope:

Value	Meaning
`all`	All objects: for example, all of the bot's chats
`own_unassigned`	Own chats and chats not assigned to anyone
`own`, `assigned`	`own` — only chats assigned to this account. `assigned` — depends on how chats are distributed in the bot: all chats, own and available, or only own

Error 403 or 404 — what is the difference

Answer	What it means	What to do
`403 access_denied`	The object exists, but the key is not authorized for it: the role lacks the necessary permission, the object is in another company or in a Space that the account has not been added to, or the chat is not assigned to the account.	Check that the account is added to the correct Space and that its role has the permission from the table above.
`404` with the code `..._not_found`	The object with this ID does not exist: there might be a typo, the object was deleted, or an ID of a different type was provided, for example, a chat ID instead of a bot ID.	Check the ID — obtain it only from API responses.