---
title: "Custom roles and permissions"
url: https://docs.corefinity.com/guides/organisation/people/custom-roles-and-permissions
type: guide
last_updated: 2026-11-13
feature: team
related:
  - https://docs.corefinity.com/api/reference/organisation/get-own-company.md
  - https://docs.corefinity.com/api/reference/organisation/update-company-settings.md
  - https://docs.corefinity.com/api/reference/organisation/get-company-details.md
  - https://docs.corefinity.com/api/reference/organisation/list-own-permissions.md
  - https://docs.corefinity.com/api/reference/organisation/list-assignable-roles.md
  - https://docs.corefinity.com/api/reference/organisation/attach-role-to-user.md
  - https://docs.corefinity.com/mcp/tools/corestack_team_members_list.md
  - https://docs.corefinity.com/mcp/tools/corestack_team_member_get.md
  - https://docs.corefinity.com/mcp/tools/corestack_team_member_invite.md
  - https://docs.corefinity.com/mcp/tools/corestack_team_member_invite_resend.md
  - https://docs.corefinity.com/mcp/tools/corestack_team_member_update.md
  - https://docs.corefinity.com/mcp/tools/corestack_team_member_remove.md
---
# Custom roles and permissions

Create a role of your own, choose its permissions, and change or delete it later.

## Before you start

- You are an owner of the organisation to create a role.
- To change a custom role you are an owner, or your role has **Edit Roles**. To delete one, **Delete Roles**.
- A custom role belongs to your organisation. The built-in [roles](/guides/organisation/people/roles) cannot be changed.

## Create a role

1. **Open Roles**

   Go to **Organisation › Roles** and choose **Create role**.

2. **Name the role**

   Enter a **Name** that says what its users do, such as `Content editor`. Choose **Create Role**.

   _Screenshot: The Role Details form with the Name field filled in as Content editor and the buttons Cancel, Create & Add Another and Create Role._

3. **Tick its permissions**

   The role opens for editing, holding no permissions. Choose **Permissions** and tick each permission the role should hold.

   _Screenshot: The Role Details page of Content editor with the Permissions tab ringed: tick boxes by area, with View Companies, View Websites and View Environments ticked._

4. **Save the role**

   Choose **Update Role**. The role is listed in **Roles** with its number of permissions.

## Give the role to a user

Choose the role under **Role** when you invite a user, or under **Roles** when you edit one: see [Users and invitations](/guides/organisation/people/users-and-invitations).

## Change a role's permissions

1. **Open the role**

   In **Roles**, choose the role's name, then **Edit role** or **Edit permissions**.

   _Screenshot: The page of the custom role Content editor: 8 of 74 permissions and 0 users, the Edit role button with its menu open on Delete role…, and the Permissions card with Edit permissions._

2. **Tick or untick permissions**

   Choose **Permissions**, tick or untick the boxes, and choose **Update Role**.

The change applies to every user who holds the role.

## Delete a role

1. **Delete it from its page**

   On the role's page, open the **…** menu beside **Edit role** and choose **Delete role…**, then **Delete**.

A role that users still hold cannot be deleted. Give each of them another role first: **Users with this role** on the role's page lists them.

## Automate this

**API:** [Create a custom role](https://docs.corefinity.com/api/reference/organisation/create-custom-role.md), scope `write`

```bash
curl -X POST https://manage.corefinity.com/api/roles/create \
  -H "Authorization: Bearer $COREFINITY_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Release managers",
    "permissions": [
      "viewUsers"
    ]
  }'
```

**MCP:** [`corestack_team_role_create`](https://docs.corefinity.com/mcp/tools/corestack_team_role_create.md), scope `write`

```json
{
  "name": "corestack_team_role_create",
  "arguments": {
    "name": "Release managers",
    "permissions": ["viewWebsites", "deployEnvironments"]
  }
}
```

**Control Panel:** Organisation › Users ([https://manage.corefinity.com/go/team](https://manage.corefinity.com/go/team))

## Related

- [Roles](/guides/organisation/people/roles): See what each role may do.
- [Users and invitations](/guides/organisation/people/users-and-invitations): Invite a user and choose their role.
- [Organisation SSH keys](/guides/organisation/access/organisation-ssh-keys): Add a key for every environment.
