# Roles and Permissions Matrix

> Source: https://agilitycms.com/docs/owners-admins/roles-and-permissions-matrix

This page puts Agility's built-in roles side by side, so you can see in one table what each role can do in an instance. It is built from the role and permission descriptions in [User Permissions](https://agilitycms.com/docs/owners-admins/user-permissions), and it then explains how [Custom Roles](https://agilitycms.com/docs/owners-admins/custom-roles), [Teams](https://agilitycms.com/docs/owners-admins/teams) and [Item-level Permissions](https://agilitycms.com/docs/owners-admins/item-level-permissions) narrow or extend it.

Roles are assigned per instance, in **Settings > User Access** (for a person) or **Settings > Team Access** (for a team). For ready-made combinations for agencies, contractors, reviewers and automation, see [Role Design Recipes](https://agilitycms.com/docs/owners-admins/role-design-recipes).

## The base permissions

Every built-in role is a bundle of these permissions. Custom Roles use the same list.

| Permission | What it grants |
| --- | --- |
| Read | See something, but not edit it. |
| Contribute | Create something, and edit what you created, but not what someone else created. |
| Edit | Change something. |
| Approve | Approve or decline something that has been requested for approval. |
| Publish | Publish or unpublish something. |
| Manage | All settings, models and reports. |
| Delete | Delete something. |
| Design / Develop | Models and fields marked "Designer Only". |
| View Reports | The Reports section. |
| Full Control | Full control over the instance, including all user management controls. |

## Built-in roles by action

"Yes" and "No" come straight from the role descriptions and the permissions chart in [User Permissions](https://agilitycms.com/docs/owners-admins/user-permissions). A numbered note means the current documentation does not settle that cell; read the note before you rely on it.

| Role | View content, pages and assets | Create items | Edit items others created | Approve or decline | Publish or unpublish | Delete items | Manage models and Designer Only fields | Settings | Reports | Manage users and roles | API keys |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| **None** | No | No | No | No | No | No | No | No | No | No | No |
| **Reader** | Yes | No | No | No | No | No | No | No | No | No | No |
| **Contributor** | Yes | Yes | No (own items only) | No | No | No | No | No | No | No | No |
| **Editor** | Yes | Yes | Yes | No | No | No | No | No | No | No | No |
| **Publisher** | Yes | Yes | Yes | See note 1 | Yes | No | No | No | No | No | No |
| **Approver** | Yes | Yes | Yes | Yes | No | No | No | No | No | No | No |
| **Delete** | Yes | Yes | Yes | No | No | Yes | No | No | No | No | No |
| **Designer** | Yes | Yes | Yes | No | No | No | Yes | Some (note 2) | No | No | See note 2 |
| **Manager** | Yes | Yes | Yes | Yes | Yes | See note 3 | Yes | Yes | Yes (note 4) | See note 5 | See note 5 |
| **Report Viewer** (note 6) | No | No | No | No | No | No | No | No | Yes | No | No |
| **Admin** | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes |

A few things the table also tells you:

- **Editor and above can manage components on a page.** The Editor description includes adding and managing components on a page, and Publisher, Approver, Delete and Designer all start from Editor.
- **Publisher, Approver and Delete are each Editor plus one permission.** None of them includes the other two. Someone who needs to approve and publish needs both roles, a Manager role, or a Custom Role.
- **Designer is the role for content architecture.** It adds models, Designer Only fields and control over which components can appear in each page zone.
- **Manager combines Approver, Publisher and Designer**, and the role description adds access to all of settings and the ability to delete groups and content lists.
- **Admin has Full Control**, which is the permission that includes all user management controls.

### Notes

1. **Publisher and approvals.** The role list gives approval to the Approver role, and the permissions chart does not tick Approve for Publisher. [Approvals and Workflows](https://agilitycms.com/docs/editors/workflows) describes Publishers approving publish requests. If a Publisher must approve, test it in your instance first, or assign Approver as well.
2. **Designer and settings.** The Designer description says it "has access to some settings" without listing which. Check in your instance before you rely on a Designer reaching a particular settings page, including API keys.
3. **Manager and Delete.** The Manager description includes Delete permissions, and Managers can delete groups and content lists. The permissions chart in User Permissions does not tick Delete for Manager. If a Manager must delete content items, confirm it in your instance.
4. **Manager and reports.** The chart does not tick View Reports for Manager, but Manager includes the Manage permission, which covers all settings, models and reports.
5. **Manager and user management.** Manager has access to all of settings. User management is described as part of Full Control, which only Admin has. Check whether your Managers can change user access before you rely on it.
6. **Report Viewer.** Report Viewer appears in the permissions chart in User Permissions with View Reports only, but not in the role list in the same article. If you do not see it when you assign a role, use a Custom Role with View Reports.

## How Custom Roles change the matrix

[Custom Roles](https://agilitycms.com/docs/owners-admins/custom-roles) let you name your own role and pick any combination of the base permissions above. Create them in **Settings > Roles** with **+ Add Role**. Custom Roles are available to Enterprise customers.

Use a Custom Role when no built-in row matches the job. Typical reasons:

- You want approve and publish without delete, which no single built-in role below Manager gives.
- You want a role name that matches your own process, such as "Legal Reviewer".
- You want reporting access on its own.

A Custom Role is still a set of the same ten permissions. It cannot grant anything that is not on the list above.

## How Teams change the matrix

[Teams](https://agilitycms.com/docs/owners-admins/teams) do not add new permissions. They change who receives a role.

- An Organization Admin creates the team and adds members from the organization's **Users** page. A user added only to a single instance cannot be used in a team.
- In each instance, **Settings > Team Access > Add Team Role** gives the team one or more roles. Every current and future member gets those roles in that instance.
- **Team roles add up.** A user on more than one team gets the roles from every team they are on.
- **Individual access wins.** If a user is on a team and has also been given individual access to the instance, the team access is ignored for that user. Remove the individual access if you want the team to control it.
- Teams can be given item-level security on pages, content and asset folders, the same as users.
- Teams are available to organizations with at least one Enterprise subscription.

## How Item-level Permissions change the matrix

[Item-level Permissions](https://agilitycms.com/docs/owners-admins/item-level-permissions) (the **Security** option on a page or content list) give a user or team extra roles on that one page or content list.

- **They only add.** Security settings grant permissions above what the user's instance role gives. You cannot use them to take a permission away on one page or list.
- **So start low.** The documented pattern is to give the user the **Reader** role for the instance, then add Editor or Publisher on only the pages and content lists they own.
- **Asset folders have their own levels.** Folder security in [Introduction to Assets](https://agilitycms.com/docs/editors/introduction-to-assets) offers three levels: Contributor (view the folder, read only), Editor (upload and change files) and Delete (Editor plus delete).

Because item-level permissions can only raise access, the instance role is the floor. Choose the lowest instance role that works everywhere, then raise it where needed.

## Access outside the matrix

- **Organization Admins** create instances and manage subscriptions and billing. Being an Organization Admin does not by itself let you log in to an instance; instance access is managed separately. See [Organization FAQ's](https://agilitycms.com/docs/owners-admins/organization-faqs).
- **Personal Access Tokens** act as the user who created them and inherit that user's permissions. They have no separate role-based access controls, and they cannot be used to create or update users. See [Personal Access Tokens](https://agilitycms.com/docs/developers/personal-access-tokens).
- **AI assistants using the Agility MCP Server** run as the signed-in user, so the same row of this table applies. See [Governing AI Access to Agility CMS](https://agilitycms.com/docs/owners-admins/governing-ai-access).
- **CLI sync in a pipeline** needs a user who is an Org Admin, an Instance Admin, or a Manager on both the source and target instances. See [CLI - CI/CD Integration Guide](https://agilitycms.com/docs/developers/cli-ci-cd-integration-guide).

## Checking who has what

The **Permissions** report, under Reports, lists the permissions granted in the instance, including global roles and the roles set on content, pages and asset folders. Use it for periodic access reviews. See [Accessing Reports](https://agilitycms.com/docs/owners-admins/accessing-reports) for the Reports section.

## Related articles

- [User Permissions](https://agilitycms.com/docs/owners-admins/user-permissions)
- [User Access](https://agilitycms.com/docs/owners-admins/user-access)
- [Custom Roles](https://agilitycms.com/docs/owners-admins/custom-roles)
- [Teams](https://agilitycms.com/docs/owners-admins/teams)
- [Item-level Permissions](https://agilitycms.com/docs/owners-admins/item-level-permissions)
- [Role Design Recipes](https://agilitycms.com/docs/owners-admins/role-design-recipes)
- [Approvals and Workflows](https://agilitycms.com/docs/editors/workflows)