---
title: "Custom Roles"
description: "A custom role is a named, account-defined role that you build from the granular permissions catalog. When none of the predefined roles fit a job function…"
url: "https://www.contentstack.com/docs/lytics/custom-roles"
product: "Contentstack"
doc_type: "guide"
audience:
  - developers
  - admins
version: "current"
last_updated: "2026-11-05"
---

# Custom Roles

## Overview

A **custom role** is a named, account-defined role that you build from the [granular permissions](/docs/lytics/granular-permissions) catalog. When none of the predefined roles fit a job function, assigning a long list of individual granular permissions to every user is tedious to set up and easy to get wrong. Instead, you define the permission shape once as a custom role, give it a name, and assign that single role.

A custom role is just a bundle of granular permissions. Its effective access is the union of the permissions you select, so anything you can express by hand-picking granular permissions you can save as a reusable role.

**Who can manage custom roles**

Creating, editing, and deleting custom roles requires the same access as managing users: the **Admin** predefined role, or a role that grants user management. You manage custom roles from a logged-in user session, not through an API token.

## Creating a custom role

Open **Custom Roles** from the account navigation (under **Users**, next to **Manage Users**) and click **Create New**.

![The Custom Roles list, reached from Account > Users > Custom Roles, with a Create New row above the existing roles](https://images.contentstack.io/v3/assets/blt2d43f51baca745a8/am2d24f09aaf7d148c/3c81095a4622021ca238cefe/custom-roles-list.png)

Fill in the role:

*   **Role name.** The display name shown wherever the role is assigned, for example _Audience Analyst_ or _Content Editor_.
*   **Slug.** A lowercase identifier derived automatically from the name. You can edit it, but it must be unique within your account and cannot collide with a built-in role. The slug is the stable identifier used in APIs.
*   **Description (optional).** A short note on what the role is for, shown to admins when they assign it.
*   **Permissions.** Select the granular permissions this role grants. The picker mirrors the **Granular Permissions** tab, with each permission grouped by feature area. Select at least one.

To start from an existing shape, use **Prefill from a predefined role** (for example, _Data Manager_) to pre-select the granular permissions equivalent to that predefined role, then add or remove individual permissions from there.

![The role editor's Permissions section, with the Prefill dropdown above granular permissions grouped by feature area and a few selected](https://images.contentstack.io/v3/assets/blt2d43f51baca745a8/am1897e6afdbd228a2/0eb59a4eb55de81a1b9a37c1/custom-roles-editor.png)

Click **Save** to create the role.

## How a custom role's permissions work

A custom role grants the union of the granular permissions you selected. The same rules that apply to granular permissions apply here:

*   **Additive.** A user who holds a custom role plus any other role gets the combination of both. There is no subtractive or "deny" behavior.
*   **Manage includes view.** Selecting the manage permission for an area already covers read access; you do not also need to add the matching view permission.
*   **Account-scoped.** A custom role applies within the single account it was created in.

Permissions resolve against the role's **current definition** every time a user authenticates. Editing a custom role's permissions immediately changes the access of everyone who holds it, so you do not need to re-assign the role.

## Assigning a custom role

Once created, a custom role appears in the **Predefined Roles** tab of the Manage Users interface, alongside the built-in roles. Assign it the same way you assign any other role: open **Manage Users**, select the user, and check the custom role.

![A user's Predefined Roles tab with the custom role listed among the built-in predefined roles](https://images.contentstack.io/v3/assets/blt2d43f51baca745a8/ama1dab0d5d4e92275/4a4615703b518d8246cf03fe/custom-roles-assign.png)

A user can hold any mix of custom roles, predefined roles, and granular permissions at once. Permissions remain additive across all of them.

## Editing a custom role

Open the role from the **Custom Roles** list and edit its name, description, or selected permissions. Because permissions resolve against the live definition, saving a change applies it to every user who currently holds the role.

## Deleting a custom role

Delete a role from the **Custom Roles** list. Before deleting, Lytics shows how many users and access tokens currently use the role so you can see the impact. Deleting a role that is still in use removes it from those users and tokens. They lose the access the role granted, but otherwise remain in place.

## Rules and limits

*   **Built from granular permissions.** A custom role bundles granular permissions. You cannot bundle broad administrative roles such as Admin into a custom role.
*   **Unique, valid slug.** Each custom role needs a slug that is unique within the account and does not collide with a built-in role slug.
*   **At least one permission.** A custom role must grant at least one granular permission.
*   **Per-account limit.** An account can define up to 100 custom roles.

For the full catalog of granular permissions you can bundle, and how permissions combine, see [Predefined Roles and Granular Permissions](/docs/lytics/granular-permissions).