API permissions (scopes)

What an API key or a connected AI assistant may read or change, how to choose its permissions and what to do when a call is refused.

Account administrators (the roles «Superadministrador», «Administrador» and «Propietario» in the Spanish app). Other people do not see the API and MCP page of Settings.

Screen and button names are given in English as a guide. The first time, the name shown in the Spanish app is in brackets.

Permissions, called scopes in the API, say what an API key or a connected AI assistant may do. They are chosen when the key is created or the assistant is connected, and they are the first thing to check when a call is refused.

How permissions are named

Most are written as an area and an action, such as orders:read. There is one for each area and action, and the full list is in the developer guide below.

…:read lets the key look at that area. It never changes anything.
…:write lets it create or change things in that area, and in some areas also delete them. Read the description of each one before you grant it.
Two exceptions: ai:ask lets it ask Filmo's AI about your data, and workflows:run lets it start your workflows.

Permission	What it allows
`account:read`	See the account's basic settings (name, time zone, currency, modules) and the key's own details
`orders:read`	See all the account's orders, with their amounts
`orders:write`	Create orders, change their header, reserve and unreserve them, cancel them, archive them and register returns
`contacts:read`	See all contacts, with their email and phone
`contacts:write`	Create, change and delete contacts and their addresses. Deleting cannot be undone and also removes the contact's notes, files and tasks; it is refused if the contact has orders or invoices
`items:read`	See the whole catalogue of items
`tasks:write`	Create, change and delete tasks. Deleting cannot be undone
`availability:read`	Check which items are free, and see the declared absences of crew, vehicles and spaces
`ai:ask`	Ask Filmo's AI about the account's data (it uses AI credits)
`workflows:run`	Run the account's workflows that have a manual trigger and a saved version. What a workflow does depends on its steps

Write permissions can do more than create and change

Some also delete, and some touch money. For example, contacts:write and tasks:write can delete, and a deletion cannot be undone. invoices:write validates and voids invoices, credit notes and proformas, and can also record or update the copy of an invoice issued by another system, with its amounts. quotes:write moves a quote's commercial status but cannot create it. The full descriptions are on the screen where you tick them.

Where you choose them

When you create an API key

The permissions come in two blocks: the ones to look up data («Consulta» in the Spanish app) and the ones that modify data («Permisos que modifican datos»), highlighted, which also holds workflows:run. Nothing comes ticked, and each block has a button to tick or untick all of it. Use it with care: a key with everything ticked can do far more than almost any tool needs.

When you connect an AI assistant

On the screen where you approve the assistant, only the permissions to look up data come ticked. Permissions that change data, workflows:run and ai:ask always start unticked, even when the assistant asks for them; the ones it asked for carry the label «Lo pide la integración» in the Spanish app (“requested by the integration”). You tick the ones you accept. The screen also shows the address the data will be sent to, and warns you if the assistant can only reply to your own computer.

Which permissions to give

You want to…	Give it
Show your orders in a report or a dashboard	`account:read`, `orders:read` and the other `:read` permissions the report uses
Send the requests from your website's form to Filmo	`account:read`, `contacts:read`, `contacts:write`. Keep in mind that `contacts:write` can also delete contacts; use a key made only for the form
Let an AI assistant answer questions	The `:read` permissions of the areas it should see. Add a `:write` permission only for what you want it to change
Run a workflow from another tool	`workflows:read` and `workflows:run`

Start small

Give a key the fewest permissions that make the tool work. If a call is refused you can create a new key with one more permission; you cannot take back what a key already did.

Some calls also need a module of your plan

A permission is not enough on its own for some areas. The CRM, incident and repair management, purchases and custom fields modules, and AI credits for ai:ask, must also be part of your plan. Without them the call is refused with a message that the plan does not include the add-on.

When something is refused

What the tool reports	Whose limit it is	How to fix it
The key does not have the required scope (403)	The key	Create a new key with that permission. For an assistant, remove the connector and add it again, approving the extra permission
You are not allowed to perform this operation (403)	The administrator who created the key: they lack the module, or the operation is for administrators only	Give that person access to the module or the administrator role, or use another administrator
The user who created the key is no longer active, or no longer an administrator (401)	The key's owner	Create a new key from an account that is an administrator
Your plan does not include the add-on this operation requires (402)	Your plan	Add the module to your plan

Developers will find every permission, with the operations it opens, in the scopes guide, and the permissions that suit each kind of AI assistant in the MCP limits guide.

Create a key and choose its permissions: Create an API key.
Who can do what in the app: Roles and permissions.
Connect an assistant: Connect an AI assistant.

Frequently asked questions

Still stuck? Contact support