*Overview › 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

| 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.

## Scopes

A key carries scopes that bound which operations it may call, such as [`orders:read`](https://docs.filmo.io/rest-api/guides/scopes#orders:read) and [`orders:write`](https://docs.filmo.io/rest-api/guides/scopes#orders:write). There are 59 of them, listed with what each opens in [Scopes](https://docs.filmo.io/rest-api/guides/scopes). Grant the least a key needs. Two deserve care: [`workflows:run`](https://docs.filmo.io/rest-api/guides/scopes#workflows:run) can modify data indirectly because the workflow does whatever its steps say, and [`ai:ask`](https://docs.filmo.io/rest-api/guides/scopes#ai:ask) spends AI credit of the account. The help center explains the same choices in [API scopes and permissions](https://www.filmo.io/help/reference/integrations-and-api/api-scopes-and-permissions).

## The person behind the key

A 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](https://docs.filmo.io/rest-api/guides/authentication) 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](https://www.filmo.io/help/reference/account-and-settings/sign-in-team-and-permissions/roles-and-permissions).

---

Canonical URL: https://docs.filmo.io/concepts/permissions  
Last updated: 2026-10-09