Roles and permissions

A role decides what a member can do in your account. Behind every button, API route, MCP tool, CLI command and AI agent tool there is one permission key, written module.action (for example documents.void). A role is simply a named list of those keys. Each account starts with five roles: Owner, Admin, Editor, Viewer and Accountant.

How permissions work

• No action without a key. Every capability declares the key it needs. There are 48 keys across every module, from businesses.view to account.delete. The full catalogue is on Permission keys.
• Checked everywhere, the same way. The check runs in the API, so the web app, REST API, MCP server, CLI, store connectors and the AI agent all refuse the same things. The web app also hides what your role cannot do.
• Read on every request. Permissions are loaded per request, not stored in your session. When a role changes, the next request already uses the new keys.
• Business scope on top. Each member also has a business scope (all businesses, or a list). The role says what they can do; the scope says where. The Owner always reaches every business.
• Keys and tokens follow their creator. An API key or MCP token carries scopes from the same list, but at call time it can only do what both its scopes and its creator's current permissions allow. If the creator loses a key, or leaves the account, their API keys and MCP tokens lose it on the next request.

The five presets

Default permission matrix

This table is the default set of keys each preset gets when your account is created, and what Reset to default restores. On Team, every role except Owner can be edited, so the roles in your account may differ from this table. The roles in Settings > Team > Roles are always the source of truth.

Business scope (all businesses or a list) applies on top of the role for every role except Owner.

The Owner role is fixed

• The Owner holds every permission key.
• The Owner role cannot be edited, reset or deleted (role_locked).
• An account always has at least one Owner (last_owner).
• account.delete and ownership transfer are Owner-only. They cannot be ticked on any other role (permission_not_grantable). account.export is also Owner-only by default.
• The Owner can never be deactivated or removed.

Nobody can grant what they do not have

Only a member whose role holds team.manage can create, edit, delete or reset roles, and even then they cannot tick a key they do not hold themselves. An Admin, for example, does not hold billing.manage by default, so an Admin cannot give billing.manage to any role, including their own. The same check stops a member from changing the role they are on in a way that adds keys. Refused changes return permission_not_grantable and nothing is saved.

Plan differences

On Free, Settings > Team > Roles shows the Owner and the Accountant as fixed, and role editing as a locked Team feature. Calls to the role capabilities return feature_locked.

If a Team account goes back to Free (for example after a failed renewal), custom and edited roles are kept but inactive, and every member except the Owner is deactivated. On re-upgrade, the roles come back as they were.

Edit a preset role

To undo your edits on a preset, choose Reset to default. Its keys go back to the defaults in the matrix above, and the reset is audited.

Through the API

curl "https://api.freeinvoiceautomation.com/v1/roles" \
  -H "Authorization: Bearer $FIA_API_KEY"

{
  "data": {
    "id": "0193f2a1-4d2e-7a10-8b3c-5e6f7a8b9c02",
    "name": "Editor",
    "preset_key": "editor",
    "is_owner": false,
    "is_active": true,
    "permissions": ["businesses.view", "documents.view", "documents.create", "..."]
  }
}

preset_key is owner, admin, editor, viewer or accountant for presets, and null for custom roles.

Errors

Related pages