# Role Design Recipes

> Source: https://agilitycms.com/docs/owners-admins/role-design-recipes

These recipes show how to combine Agility's roles, [Teams](https://agilitycms.com/docs/owners-admins/teams), [Custom Roles](https://agilitycms.com/docs/owners-admins/custom-roles) and [Item-level Permissions](https://agilitycms.com/docs/owners-admins/item-level-permissions) for common situations. Each one follows the same least-privilege rule that [User Permissions](https://agilitycms.com/docs/owners-admins/user-permissions) recommends: start with the minimum and add only what the job needs.

For what each built-in role can do, see the [Roles and Permissions Matrix](https://agilitycms.com/docs/owners-admins/roles-and-permissions-matrix).

## Three rules every recipe relies on

1. **The instance role is the floor.** Item-level permissions can add access on a page, content list or asset folder, but they cannot remove it. Pick the lowest instance role that is right everywhere, often **Reader**, then raise it where needed.
2. **Team roles add up, and individual access overrides teams.** A user on two teams gets both teams' roles. A user who also has individual access to the instance is governed by that individual access, and the team access is ignored.
3. **Publishing is a separate permission.** Editor, Contributor, Approver and Delete cannot publish. If someone should not take content live, leave Publish out and turn on approvals for the content they work on (see [Approvals and Workflows](https://agilitycms.com/docs/editors/workflows)).

Some recipes use Teams or Custom Roles, which need an Enterprise subscription. Where that matters, the recipe gives an alternative.

## Agencies and implementation partners

**Goal:** an outside agency works in one or more of your instances, and you can remove them all at once.

1. **Create a team for the agency** in your organization (Enterprise). Add each agency person from the organization's **Users** page, then add them to the team. A user added only to a single instance cannot be used in a team.
2. **Give the team a role in each instance** under **Settings > Team Access**:
   - Content agency: **Editor**, so they can create and change content and manage components, but not publish.
   - Development agency that builds models and components: **Designer**.
   - Agency that runs content syncs between instances with the CLI: **Manager** on both instances. The [CLI - CI/CD Integration Guide](https://agilitycms.com/docs/developers/cli-ci-cd-integration-guide) requires Org Admin, Instance Admin, or Manager on both source and target.
3. **Keep publishing with your team.** Turn on **Requires Approval** for pages and **Enable Approval Workflow** for content lists the agency touches, and give Approver or Publisher only to your own people.
4. **Do not also add agency users individually** to the instance. Individual access overrides team access, so a stray individual grant survives when you remove someone from the team.
5. **Offboarding:** remove people from the team, or remove the team's role from the instance. Organization Admin is a separate grant; only give it to an agency if it must create instances or manage billing.

Without Teams, assign the same roles per person in **Settings > User Access**, and keep a list of who to remove.

## Regional and locale teams

**Goal:** a regional team edits its own content without changing other regions'.

The documented controls are the instance role, item-level permissions on pages and content lists, and folder security on assets. None of the documented settings is per locale. Choose a structure that maps regions onto those controls:

- **One instance per region.** Instances are fully separate in content, assets and editor team (see [Using Agility for Multiple Sites](https://agilitycms.com/docs/overview/using-agility-cms-for-multiple-sites)). Give each regional team a role only in its own instance. This is the cleanest separation.
- **One instance, regional pages and lists.** Give every regional editor **Reader** on the instance, then use item-level security to grant **Editor** or **Publisher** on that region's pages and content lists. With Teams, create one team per region and grant the security to the team.
- **Regional asset folders.** Put each region's files in its own folder and give that region **Editor** in the folder's security settings, so they can upload and change files there and only view elsewhere.

If regions share content lists and differ only by locale, these controls cannot keep one region out of another's locale. Use a review step instead: turn on approvals and keep Approve or Publish with a central team.

## Freelancers and contractors

**Goal:** a short-term writer creates content and someone on staff reviews it.

- **Simplest:** give the instance role **Contributor**. A Contributor can create pages and content items and edit only what they created, not anyone else's, and cannot publish or delete.
- **Narrower:** give **Reader** on the instance and item-level **Editor** on only the content list or page they are hired for.
- **Assets:** if they need to upload files, give them **Editor** in the security settings of one working folder.
- **Review:** turn on approvals for the content they work on, so their changes wait for your Approver or Publisher.
- **Offboarding:** delete the user in **Settings > User Access** when the engagement ends. Review the **Permissions** report to find item-level grants you gave them.

## Reviewers and stakeholders

**Goal:** people who need to look at content, sign it off, or read reports, without changing it.

| Need | Role | Notes |
| --- | --- | --- |
| View content, pages and assets only | **Reader** | Cannot save. Good for stakeholders and for piloting AI assistants read-only. |
| Approve or decline requests | **Approver** | Approver also has Editor permissions, so it can change content too. |
| Approve without editing | A Custom Role (Enterprise) with Read and Approve | Test it in your instance before you roll it out. |
| Approve and publish | **Approver** plus **Publisher**, **Manager**, or a Custom Role with Approve and Publish | Manager also brings models and settings. |
| Reports only | **Report Viewer**, or a Custom Role with View Reports | See the note on Report Viewer in the [matrix](https://agilitycms.com/docs/owners-admins/roles-and-permissions-matrix). |

To make reviewers part of the process, turn on approvals for the pages and content lists they review. See [Approvals and Workflows](https://agilitycms.com/docs/editors/workflows).

## Automation and AI service accounts

**Goal:** a script, pipeline or AI agent changes content, and you can see and limit what it does.

Agility has no separate service-account type. Automation runs as an Agility user, and every permission rule on this page applies to it.

1. **Create a dedicated automation user** for the job, with access only to the instances it works in. Its changes are then recorded against that user in version history, apart from your people.
2. **Give it a least-privilege role.** Start from **Reader** and use item-level permissions to grant Editor, and Publish only if it publishes, on the lists and pages it owns. Or define a Custom Role. Leave out Delete and model permissions unless the job needs them.
3. **Choose how it signs in:**
   - **Unattended scripts and pipelines:** a [Personal Access Token](https://agilitycms.com/docs/developers/personal-access-tokens). A token belongs to the user who creates it and inherits that user's permissions, so create it while signed in as the automation user. Tokens last at most two years; set a shorter expiry, store the token in a secrets manager and rotate it. A token cannot create or update users.
   - **An AI assistant through the Agility MCP Server:** sign the client in with OAuth as the automation user, not as a person.
   - **CLI sync between instances:** the token's user needs Org Admin, Instance Admin, or Manager on both instances.
4. **Keep workflow deliberate.** Saves land in Staging. Publishing needs the Publish permission, and approvals apply the same as for people.

The full rollout guidance, including levels of autonomy, confirmation prompts and logging, is in [Governing AI Access to Agility CMS](https://agilitycms.com/docs/owners-admins/governing-ai-access).

## Review access regularly

- Run the **Permissions** report, which lists the permissions granted in the instance, including roles set on content, pages and asset folders.
- Check team membership in your organization's **Teams** page.
- Remove users and tokens that are no longer needed.

## Related articles

- [Roles and Permissions Matrix](https://agilitycms.com/docs/owners-admins/roles-and-permissions-matrix)
- [User Permissions](https://agilitycms.com/docs/owners-admins/user-permissions)
- [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)
- [Governing AI Access to Agility CMS](https://agilitycms.com/docs/owners-admins/governing-ai-access)
- [Personal Access Tokens](https://agilitycms.com/docs/developers/personal-access-tokens)