Skip to content
FlagSwiftDocs

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.manage permission, 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#

  1. 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.

  2. Name it and pick a base

    The editor opens as a side sheet titled New custom role. Fill in the first fields:

    Fields
    FieldRuleDescription
    NameRequired, up to 40 charactersUnique 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 onDefault ViewerRelease 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.
    DescriptionUp to 200 charactersShown under the name in the list. Without one the list says Based on and the base role.
  3. 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.read ticked.

    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.
  4. 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.

  5. 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.

Request
# 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
  }'
Response
{
  "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.deactivate and the system.* permissions stay with the owner and system admins; member management, roles.manage and 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

Editing a role changes access for everyone on it straight away. A role cannot be deleted while someone holds it or an open invitation uses it. Move people to another role first.

Good to know#

Copy the closest role, then remove

It is quicker to start from the built-in role nearest the job and clear what you do not want than to build from a single permission. Review the production switch last: it is the one setting with the largest effect.
What happens to people if I delete a role?
The delete is refused while anyone holds the role. If a role is ever removed some other way, its members fall back to Viewer rather than gaining access.
Can I rename a role?
Yes. Edit it and change the name. The new name must still be unique and not a built-in role name. People on the role keep it.
Can a custom role approve releases?
Yes, by ticking Approve or reject releases under Releases and safety. An environment that requires approval still needs a second person, because by default the author of a release cannot approve their own.
Why is the role count higher than I ticked?
Matching view permissions are added automatically so that someone who can change something can also see it.

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.created in the audit log. Edits are role.updated and deletes are role.deleted.