Core concepts
Permissions
A refusal has three different causes: the key lacks a scope, the key's owner lacks a permission, or the account lacks an add-on. Each has a different status or code and a different fix.
Three kinds of refusal
Link to this section: Three kinds of refusal| Status and code | It is about | How to fix it |
|---|---|---|
403 insufficient_scope | The key. It does not carry the scope the operation requires, named in requiredScope. | Reissue the key with that scope. |
403 forbidden | The owner of the key. The key is right, but its owner lacks the module, organization or administrator permission the operation demands. | An administrator of the account grants it. |
402 addon_required | The add-on. The account has not contracted, or has let expire, the add-on of that module, and requiredAddon names it. No role bypasses it. The API and MCP are not an add-on. | Add the add-on to the subscription. See Plans and add-ons. |
Telling them apart matters: sending all three to the same place sends you debugging in the wrong place two times out of three.
A key carries scopes that bound which operations it may call, such as orders:read and orders:write. There are 59 of them, listed with what each opens in Scopes. Grant the least a key needs. Two deserve care: workflows:run can modify data indirectly because the workflow does whatever its steps say, and ai:ask spends AI credit of the account. The help center explains the same choices in API scopes and permissions.
The person behind the key
Link to this section: The person behind the keyA key hangs from an administrator of the account, and the actor of everything it writes is that administrator, the key owner. If the account has the activity log, which is an add-on, it marks these changes as coming from the API (and from MCP, for assistants), so they can be told apart from changes made in the app. That condition is checked on every request, not only when the key is created. See Who owns the key for the rest.
| What changed | Response |
|---|---|
| The person who created the key left the account or was deactivated | 401 api_key_owner_inactive |
| The person is no longer an administrator | 401 api_key_owner_not_admin |
If your integration suddenly receives one of these, the key is fine and the role of its owner changed. Reissue the key from an account that is still an administrator. Plan for that: use a key owned by someone who is unlikely to leave, and monitor for these codes. Roles inside the app are described in Roles and permissions.
Related pages
Link to this section: Related pagesGuides
Authentication
Every operation requires an API key sent as a bearer token. Only an administrator can create a key, and the key acts as that administrator, so decide who owns it before you create it.
Guides
Scopes
A key carries scopes; each operation requires exactly one. Grant the fewest you need.
Core concepts
Plans and add-ons
The API and MCP are included in any paid plan; they are not an add-on. Access needs an administrator and the API switched on by Filmo for your environment; some modules need their add-on. Call
GET /apito see which add-ons the account has today./v1 /account
Was this page helpful?