Skip to content
FlagSwiftDocs

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.invite to invite, members.update to change roles, roles.manage to 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.
Who can do what
CapabilityRolesDescription
Create and edit flags, targeting and segmentsSystem admin, Admin, Release manager, Product manager, DeveloperA 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 productionSystem admin, Admin, Release manager, DeveloperProduct managers plan and propose instead.
Toggle, roll out and change targeting in productionSystem admin, Admin, Release managerWithdrawn for developers and product managers.
Propose a releaseSystem admin, Admin, Release manager, Product manager, DeveloperProposing never applies a change by itself.
Approve or reject a releaseSystem admin, Admin, Release managerSubject to the environment approval setting.
Use the kill switchSystem admin, Admin, Release managerLifting it needs the same role.
Delete flags, segments, projects and environmentsSystem admin, AdminArchiving a flag is reversible, so developers and release managers can do that.
See API keysSystem admin, Admin, Release manager, Developer, AuditorCreating, rotating, revoking and copying keys is admin only.
Read the audit logAll except ViewerA developer sees only their own entries.
Export the audit logSystem admin, Admin, AuditorDevelopers cannot.
Invite people, change roles, manage custom rolesSystem admin, AdminThese stay with admins.

Ownership is not a role

One admin is the owner of the organization. Only the owner can transfer ownership, reset an admin's password, remove an admin or make someone an admin. The owner also holds the only right to deactivate the organization.

Walk through it#

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

  3. The top of the Roles & permissions tab: your own role, then the custom roles with their permission counts. The capability table follows below them, one column per role, with your own column marked (you).
  4. 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.
  5. 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 a member.role_changed entry 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.

Request
# 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"}'
Response
{
  "status": "success",
  "message": "Role updated successfully",
  "data": { "id": "MEMBER_ID", "role": "release_manager" }
}

Good to know#

Start narrow, widen when asked

Give new people Developer or Viewer first. It is a smaller step to widen access later than to discover someone changed production by accident. Auditors are the right role for compliance reviewers who should read everything and change nothing.

Custom roles on a Developer base see only their own audit entries

The audit log limits the Developer role to its own entries, and a custom role follows its base role for this. Base a role on Auditor or Release Manager if the person needs to see everyone's activity.
Can one person hold two roles?
No. A member has exactly one role. Create a custom role that combines the permissions you need.
Do role changes need the person to sign in again?
No. Role changes and edits to a custom role take effect on the person's next request.
Who is the owner, and can there be two?
The owner is the admin who founded the organization. There is exactly one, and the owner can hand the status to another admin.
Does a role limit what an API key can do?
A key can never hold a scope its creator could not use, so a key made by someone with less access is narrower. Keys themselves are not roles. See Create, rotate and revoke API keys.

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.