Give people the right access
Invite people with a role that matches what they do, and shape a custom role when none of the built-in ones fit.
- Time
- About 12 min
- Who can do it
- Admins, or anyone with members.invite and members.update
- Where
- Members, in the console
- You finish with
- Each person on a role that fits their job
What and why#
Every member of your organization holds exactly one role, and the role decides what the console and the Dashboard API let that person do. Roles exist so that the people who build flags, the people who release them and the people who only need to look can each have the access their job needs and no more.
The production rule#
Most of the difference between roles comes down to one question: who may change a flag in a production environment. Developers and product managers can build and test everywhere, but toggles, rollouts, targeting changes and the kill switch are read-only for them in an environment marked as production. Release managers and admins keep write access there. Pair this with approval on production and a change needs two people.
Roles, owners and permissions#
A role is a named bundle of permissions such as flags.toggle or audit.export. The built-in roles are fixed. A custom role is a set of permissions you choose. The owner is the admin who founded the organization. It is a status, not a role.
Before you start#
- You need to be an admin, or hold the permissions for what you want to do:
members.inviteto invite,members.updateto change roles,roles.manageto create custom roles. - A rough idea of who should be able to change production. That one decision shapes most of the roles.
- Only the owner can invite someone as an admin or change an admin's role, and only a system admin can grant the System admin role.
Pick a built-in role#
- System admin holds every permission, including the instance-level ones (
system.read,system.manage) that an Admin lacks. Only a system admin can hand this role out, and the role pickers show it only to system admins. Day to day, give people Admin instead. - Admin manages members, roles, environments, keys and alerts, and is the only role that can delete.
- Release Manager runs releases in every environment including production, approves or rejects them and holds the kill switch.
- Product Manager plans what ships: edits flags, targeting and segments and proposes releases, but does not apply them.
- Developer builds with flags and is read-only for toggles, rollouts, targeting and the kill switch in production.
- Auditor reads everything, including the full audit log and its export.
- Viewer reads projects, environments, flags, metrics and releases.
| Capability | Roles | Description |
|---|---|---|
| Create and edit flags, targeting and segments | System admin, Admin, Release manager, Product manager, Developer | A product manager cannot toggle or roll out. Segments used by production flags are off limits wherever production targeting is. |
| Toggle, roll out and roll back outside production | System admin, Admin, Release manager, Developer | Product managers plan and propose instead. |
| Toggle, roll out and change targeting in production | System admin, Admin, Release manager | Withdrawn for developers and product managers. |
| Propose a release | System admin, Admin, Release manager, Product manager, Developer | Proposing never applies a change by itself. |
| Approve or reject a release | System admin, Admin, Release manager | Subject to the environment approval setting. |
| Use the kill switch | System admin, Admin, Release manager | Lifting it needs the same role. |
| Delete flags, segments, projects and environments | System admin, Admin | Archiving a flag is reversible, so developers and release managers can do that. |
| See API keys | System admin, Admin, Release manager, Developer, Auditor | Creating, rotating, revoking and copying keys is admin only. |
| Read the audit log | All except Viewer | A developer sees only their own entries. |
| Export the audit log | System admin, Admin, Auditor | Developers cannot. |
| Invite people, change roles, manage custom roles | System admin, Admin | These stay with admins. |
Ownership is not a role
Walk through it#
Invite people with a role
Open User management, choose Invite member, enter a full name and work email and pick a role. An invitation is a single-use link for one address and one role, and it expires after 7 days. To bring in a team, use Bulk invite for up to 50 people at once with the same role; each address succeeds or fails on its own. The full flow is in Invite and manage members.
The Invite member dialog. The Role list shows only roles you are allowed to hand out, each with its one-line description. You should see. The invitation dialog shows the link, the email as a username and a one-time password, and the person appears under Pending invitations.See exactly what each role allows
Owners and admins see a Roles & permissions tab on the Members page. It lists every built-in and custom role with its member count and a table of capabilities with a tick for allowed, a dash for not allowed and a note where the access is limited, such as own activity only in the audit log. The table is computed from the same rules the server enforces, so it cannot drift.
Create a custom role when needed
A custom role is a named set of permissions on top of a built-in base role. Choose the base, tick the permissions and decide whether the role may change production with
productionWrite. Production stays blocked until you allow it. You can have up to 25 custom roles. The detail is in Create a custom role.What you can delegate
Deactivating the organization and instance settings stay with the owner and system admins and cannot be given to a custom role. You can only grant permissions you hold yourself, and read access for a permission is added for you.Change a role later
On the Members tab, use the role menu on a person's row. A row only offers roles you are allowed to hand out, and picking one opens a confirmation. People on an edited custom role get the new permissions straight away. A role cannot be deleted while someone holds it or an open invitation uses it.
The Members tab. The owner badge is green, the role menu is replaced by a plain badge on your own row and on rows you may not change. Each role has its own badge colour: owner green, system admin violet, admin blue, release manager amber, product manager pink, developer orange, auditor teal, viewer grey and custom roles teal. The confirmation after you pick a new role from the menu, and the same dialog while the change is saved. Nothing changes until you press Change role. When the person is an admin being demoted, the text says their administrator access ends straight away and the button is red. You should see. The row shows the new role label. The audit log has amember.role_changedentry with the before and after role.
Do it with the API
This is the Dashboard API: it needs a signed-in session cookie, not an API key, and it needs members.update. The role is a built-in role value such as developer or custom:<id> for a custom role. See the Members and invitations API for every call.
# Sign in once and keep the cookie (the Dashboard API acts as a person)
curl -s -c jar.txt -X POST https://flags.example.com/api/auth/login \
-H "Content-Type: application/json" \
-d '{"email":"you@example.com","password":"..."}'
# Change a member's role. {id} is the id from GET /api/members
curl -s -b jar.txt -X PATCH https://flags.example.com/api/members/MEMBER_ID \
-H "Content-Type: application/json" \
-d '{"role":"release_manager"}'{
"status": "success",
"message": "Role updated successfully",
"data": { "id": "MEMBER_ID", "role": "release_manager" }
}Good to know#
Start narrow, widen when asked
Custom roles on a Developer base see only their own audit entries
Can one person hold two roles?
Do role changes need the person to sign in again?
Who is the owner, and can there be two?
Does a role limit what an API key can do?
If something goes wrong#
Only the owner can make someone an administrator
Why: Admin is the one role that only the owner (or a system admin) can hand out or change.
Fix: Ask the owner to make the change, or have the owner transfer ownership to you first.
This is the last administrator. Make someone else an administrator first
Why: An organization must always keep someone who can manage members.
Fix: Promote another person to Admin, then change or remove the first one.
A person cannot do something their role should allow
Why: The action is probably in a production environment, where Developers and Product managers are read-only, or the role is a custom role without that permission.
Fix: Check the Roles & permissions table. For a custom role, tick the permission or turn on productionWrite.
I do not see the Roles & permissions tab
Why: The tab is shown only to people who can change members' roles, by default owners and admins.
Fix: Ask an Admin, or read the built-in role list above.
A member's row shows a role badge and no role menu
Why: It is your own row, or the owner and admin rules lock it for you. Hover the badge to see why.
Fix: Ask the owner to change it.
The role cannot be deleted
Why: Someone still holds the custom role, or an open invitation uses it.
Fix: Move the people to another role and revoke the open invitations, then delete it.
What to check#
- Sign in as the new person, or ask them, and confirm they can do the one thing the role is for and nothing in production they should not.
- Auditors can open the audit log and export it. Developers cannot export it.