Create a custom role
Build a role with exactly the permissions a job needs, when none of the built-in roles fit.
- Time
- About 10 min
- Who can do it
- Admins (roles.manage)
- Where
- Members, Roles & permissions tab
- You finish with
- A named role you can assign to people and invitations
What and why#
The seven built-in roles cover most teams, but some jobs sit between them: a QA lead who may switch flags in staging and read the audit log, a support engineer who may only view, a release coordinator who may approve but never delete. A custom role lets you name that job and give it exactly the permissions it needs.
How a custom role is made#
A custom role has three parts: a list of permissions that decides what it can do, a base role that decides how the owner and admin rules treat it and how the audit log scopes it, and a production switch that decides whether it may change production environments at all.
Why not just use Admin?#
Admin can delete things and manage people, and those powers cannot be given to a custom role: inviting, changing and removing members, managing roles, every delete permission, deactivating the organization and instance settings are not offered in the role editor. Keep a role built for one job to the permissions that job needs.
Before you start#
- You need to be an admin. Creating and editing custom roles takes the
roles.managepermission, which stays with admins. - A clear picture of the job. For example, “can switch flags on and off in staging, can read the audit log, cannot touch production”.
- You can only give a role permissions you hold yourself. A permission you lack is greyed out in the editor.
Walk through it#
Open the role editor
Go to Members, open the Roles & permissions tab and choose New role. The tab is only shown to people who can change members' roles. The button is disabled once you reach 25 custom roles.
Name it and pick a base
The editor opens as a side sheet titled New custom role. Fill in the first fields:
Fields Field Rule Description Name Required, up to 40 characters Unique in your organization, ignoring case, and not the name of a built-in role such as Developer or Viewer. The placeholder suggests “Support engineer”. Based on Default Viewer Release Manager, Product Manager, Developer, Auditor or Viewer. It decides how the owner and admin rules treat the role and how much of the audit log it sees. It never makes someone an admin. Description Up to 200 characters Shown under the name in the list. Without one the list says Based on and the base role. Start from a built-in role, then adjust
Start from appears when you create a role. It copies what Viewer, Developer, Product Manager, Release Manager or Auditor can do, limited to what you hold, and sets the base to match. Then tick or clear permissions. A new role starts with only
flags.readticked.Permissions are grouped as Flags, Rollouts and targeting, Segments, Releases and safety, Projects and environments, API keys, Insight, and People and organization. Each group has a Select all or Clear link, and a counter shows how many are selected. Pick at least one.
The New custom role sheet. Permissions you do not hold yourself are greyed out. The counter and Create role button update as you tick. You should see. The counter reads the number of permissions you chose, and the Create role button turns on once there is a name and at least one permission.Decide about production
Can change production environments is off by default. While it is off, toggles, rollouts, targeting changes and the kill switch are read-only in environments marked as production, like a developer. Turn it on only for people who should apply changes there. You can only switch it on if you can make those changes yourself; otherwise the switch is disabled and says so.
Save and assign it
Choose Create role. The role now appears in the role pickers when you invite someone or change a member's role, under the name you chose.
Read access comes with write access
Anyone who can change something can also see it, so the matching view permissions are added for you. Every role also gets the right to view the organization, projects, environments and flags. After saving, the permission count can be higher than the number you ticked.You should see. The role is listed with its description, permission count, a note if it can change production, and a count of people on it.
Do it with the API
Use the returned ref (custom:<id>) wherever a role is accepted, for example in an invitation or PATCH /api/members/{id}. PUT /api/roles/{id} replaces a role with the same body and DELETE /api/roles/{id} removes it. The ids in the response above are illustrative. See the custom roles API.
# Needs a signed-in session (cookie jar from POST /api/auth/login) and roles.manage
curl -s -b jar.txt -X POST https://flags.example.com/api/roles \
-H "Content-Type: application/json" \
-d '{
"name": "QA lead",
"description": "Switches flags in staging and reads the audit log",
"baseRole": "developer",
"permissions": ["flags.toggle", "releases.create", "audit.read"],
"productionWrite": false
}'{
"status": "success",
"message": "Role created",
"data": {
"kind": "custom",
"id": "9b2f0c1e",
"ref": "custom:9b2f0c1e",
"name": "QA lead",
"description": "Switches flags in staging and reads the audit log",
"baseRole": "developer",
"permissions": [
"organization.read", "projects.read", "environments.read",
"flags.read", "flags.toggle",
"releases.read", "releases.create",
"audit.read"
],
"productionWrite": false,
"members": 0,
"createdByEmail": "you@example.com",
"updatedAt": "2026-10-03T09:30:00.000Z"
}
}What you cannot delegate#
organization.deactivateand thesystem.*permissions stay with the owner and system admins; member management,roles.manageand the delete permissions stay with admins. None of them can be given to a custom role. Everything else is on the list if you hold it yourself.- A role cannot be based on an admin role. The base is always Release Manager, Product Manager, Developer, Auditor or Viewer.
- You cannot give a role more than you hold. A permission you lack is greyed out, with a hint on hover.
- At most 25 custom roles per organization.
Changes apply at once
Good to know#
Copy the closest role, then remove
What happens to people if I delete a role?
Can I rename a role?
Can a custom role approve releases?
Why is the role count higher than I ticked?
If something goes wrong#
That name belongs to a built-in role. Choose another
Why: The name matches System admin, Admin, Release manager, Product manager, Developer, Auditor or Viewer.
Fix: Pick a different name, such as QA lead or Support engineer.
A role with this name already exists
Why: Names are unique in your organization, ignoring case.
Fix: Choose another name, or edit the existing role.
You can't give a role permissions you don't hold yourself
Why: The role includes a permission your own role lacks. The editor greys these out, but an API call can still ask for them.
Fix: Remove the permission, or ask an admin who holds it to create the role.
An organization can have at most 25 custom roles
Why: The limit is reached.
Fix: Delete a role nobody uses, or extend one that already fits.
Choose at least one permission
Why: No permission is ticked, so Create role stays disabled in the editor, and the API refuses an empty list.
Fix: Tick at least one permission.
Keep the name under 40 characters (or the description under 200)
Why: The name or description is over its limit.
Fix: Shorten it. The editor stops typing at the limit, but the API checks it too.
A custom role cannot hold organization.deactivate (or a system.* permission)
Why: Those permissions can never be given to a custom role.
Fix: Leave them out. They stay with admins.
You can't allow production changes because you can't make them yourself
Why: Can change production environments needs you to hold that power too.
Fix: Ask an Admin or a Release manager to create the role.
N people have this role. Move them to another role first
Why: A role in use cannot be deleted.
Fix: Change those members to another role. Revoke any open invitation that uses the role as well.
What to check#
- The role shows its permission count and member count on the Roles & permissions tab.
- Ask a person on the role to try the one thing it is for, and one thing it should not allow, such as a production toggle.
- Find
role.createdin the audit log. Edits arerole.updatedand deletes arerole.deleted.