Project roles, permission matrix, token scopes, and access control for teams
Last updated November 14, 2026
Roles & Permissions
Flaggr uses role-based access control (RBAC) at the project level. Each team member is assigned a role that determines what they can do.
Project Roles
| Role | Description |
|---|---|
| Owner | Full control. Can delete the project, grant or remove the owner role, and transfer ownership. |
| Admin | Manage everything except deleting the project. |
| Member | Create, read, and update flags and services. Cannot manage team or settings. |
| Viewer | Read-only access to flags, services, and audit logs. |
Permission Matrix
| Action | Owner | Admin | Member | Viewer |
|---|---|---|---|---|
| View flags | Yes | Yes | Yes | Yes |
| Create flags | Yes | Yes | Yes | No |
| Update flags | Yes | Yes | Yes | No |
| Toggle flags | Yes | Yes | Yes | No |
| Delete flags | Yes | Yes | No | No |
| View services | Yes | Yes | Yes | Yes |
| Create services | Yes | Yes | Yes | No |
| Delete services | Yes | Yes | No | No |
| View audit logs | Yes | Yes | Yes | Yes |
| View members | Yes | Yes | Yes | Yes |
| Add members | Yes | Yes | No | No |
| Remove members | Yes | Yes | No | No |
| Change roles | Yes | Yes | No | No |
| Grant / change / remove owners | Yes | No | No | No |
| Leave the project | Yes* | Yes | Yes | Yes |
| Manage settings | Yes | Yes | No | No |
| Create tokens | Yes | Yes | No | No |
| Revoke tokens | Yes | Yes | No | No |
| Delete project | Yes | No | No | No |
| Change slug | Yes | No | No | No |
*Not the last owner.
API Token Scopes
API tokens have their own permission model on top of project roles. A project API token acts as the person who created it, only inside its project, and never above that person's current role.
Scoped Tokens
A scoped project API token's access is a list of scopes, each <level>:<identifier>:<tier>: project:<id> for the whole project, service:<id> (the service's ID, not its slug), environment:<slug> or flag:<key>, with read, write or admin. Rules add up. A service, environment or flag scope counts only on requests that name that service, environment or flag, so project-wide requests need a project scope. Scoped tokens are long-lived, and their scopes are checked when they are created. See How API tokens are scoped.
Whole-Project Tokens
A token made with the legacy permissions body has the tier its bits give:
{
"permissions": {
"read": true,
"write": true,
"delete": false
}
}| Permissions | Tier | Grants |
|---|---|---|
read | read | Evaluate flags; read flags, services, environments, metrics and audit data |
read + write | write | Also create, update and toggle flags, services, rollouts and alert rules |
+ delete | admin | Also delete flags, services and monitors, change project settings and environments, list, rename and revoke the project's tokens |
No API token can manage members, teams or invitations, mint credentials, or create and delete projects. See How API tokens are scoped.
Legacy JWT Scopes
Legacy JWT tokens (created with scopes and no tokenType) use the same scope grammar, checked on each request. Deleting needs admin.
For automation across projects, use a personal access token instead: it acts as you, capped by a read, write or admin tier.
Always create tokens with the minimum scopes they need. Apps should use read-only SDK keys. Only CI/CD or admin tools need write access.
Team Management
Inviting Members
Invite users by email. The invitation expires after 7 days.
POST /api/projects/{id}/invitations
{ "email": "alice@example.com", "role": "member" }You can't invite someone as owner — invite them, then an owner promotes them. To transfer ownership, an owner promotes another member to owner (PATCH /api/projects/{id}/members/{memberId} with { "role": "owner" }), then demotes themselves.
Adding someone by email always sends an invitation: POST /api/projects/{id}/members and POST /api/organizations/{orgId}/members with { "email", "role" } answer 202 { invited: true, invitation }, exactly like POST .../invitations. The answer is the same whether or not the address has a Flaggr account, because Flaggr never looks an address up and adds the account. To add someone directly, send { "userId", "role" }. This works only for people who already share an organization or a project with you; any other ID, including one that doesn't exist, gets 404.
Invitations are emailed with a single-use accept link that expires after 7 days. Rules:
- one pending invitation per address (
409— revoke it first); - you can't invite yourself;
- each person can send 20 invitations an hour (
429); attempts refused because the address is already a member, already has a pending invitation, or the plan has no free seat count toward it too; - a dashboard session needs a verified email address to invite anyone, add someone by user ID, or change anyone's role or access overrides (
403"Verify your email address first", codeEMAIL_NOT_VERIFIED), so an account signed up with someone else's address can't let others in before the address's owner takes it over; personal access tokens and connectors aren't asked again (creating them already needed a verified session); the console's invite and role dialogs show Send verification email and I've verified — retry, which repeats the same change; - pending invitations hold a seat on your plan (
402at the limit); an organization invitation holds one on every project in the organization; - API tokens and personal access tokens can't create invitations;
- the accept token is returned only to dashboard sessions and never appears in invitation lists.
Revoking Invitations
DELETE /api/projects/{id}/invitations/{invitationId}Needs manage_members. Only pending invitations can be revoked: an accepted one answers 409 "Invitation has already been accepted". If someone accepts while you revoke, the answer is the same 409, and the accepted invitation stays as the record of that acceptance. For organizations: DELETE /api/organizations/{orgId}/invitations?invitationId={id}, which works the same way (revoking an accepted organization invitation is now 409 too).
Accepting Invitations
- The emailed link opens
/invitations/accept, which callsPOST /api/invitations/acceptwith{ "token": "..." }— the same endpoint serves project and organization invitations. - Accept from a signed-in browser session (not an API token, personal access token or connector), with a verified email address matching the invitation.
- Links work once and expire after 7 days.
- The inviter's access is checked again at acceptance: if they were removed or demoted, or can no longer grant the role, the invitation is withdrawn ("This invitation is no longer valid").
- Response:
{ kind, membership, project | organization }. Statuses:403wrong address, unverified email ("Verify your email address first"), own invitation or withdrawn;404unknown link (including one withdrawn because its addressee was removed) or deleted project/org;409already accepted or already a member;410expired;402plan limit (for an organization invitation: a project in the organization has no free seat).
Changing Roles
PATCH /api/projects/{id}/members/{memberId}
{ "role": "admin" }- Owners assign any role, including owner.
- Admins assign admin, member or viewer. They never grant owner, change or remove an owner, add themselves, or raise their own role; lowering it is allowed.
- Per-environment and per-service access overrides follow the same rules (
owneroverrides are owner-only). - Access overrides apply wherever a request acts on one service or environment: flag reads and writes (including create, RUM optimization, site guardrails and lifecycle overrides); the flag history, lifecycle, audience, code references, RUM impact and contexts views; watching a flag; the service routes (
/api/services/{id}/…) and site health; promotion (read on the source environment); and evaluation, OFREP, Connect, gRPC-Web and event ingestion when they run on your session rather than an SDK key. Flag lists and exports leave out flags in a service or environment set tonone. - Every project keeps at least one owner (
400). - Your dashboard session needs a verified email address (
403EMAIL_NOT_VERIFIED). This also covers access overrides andupdate_roleoperations inPOST /api/projects/{id}/members/bulk. Removing members and leaving don't need it. - Ownership changes (granting, changing or removing owner) are dashboard-only for MCP connectors and project API tokens; personal access tokens need the admin tier with owner actions allowed.
- If someone changed the member at the same moment, you get
409"Membership changed — reload and try again".
Removing Members
DELETE /api/projects/{id}/members/{memberId}Removing a member revokes their access immediately. It also removes them from the project's teams, withdraws pending invitations addressed to them (an old emailed link can't bring them back), and withdraws pending invitations they created and can no longer back. If the invitations addressed to them can't be withdrawn, the removal fails with 500 and changes nothing, so retry it. Any member can leave by deleting their own membership; the last owner can't.
API tokens act as the person who created them, so a removed member's tokens stop working for management calls — but they keep evaluating flags until revoked. When removing a team member, also revoke the API tokens they created.
Organizations
The same rules apply with organization roles (owner, admin, member, billing; admins may assign admin, member or billing).
- Organization invitations are emailed and accepted through the same link; owner can't be invited.
- Removing someone from an organization also removes their direct memberships and team seats in the organization's projects.
- Only an organization owner can remove someone who owns one of its projects; that owner first becomes the direct owner of any project the person was the last owner of.
- Members may leave unless they are the last owner of an organization project (
400, with the projects listed). - Removing someone from an organization, or leaving it, also withdraws pending invitations addressed to them in the organization and all of its projects, and stops SSO just-in-time provisioning from adding them back on their next SSO sign-in. Re-adding them, or their accepting an invitation, lifts that block. Also deprovision removed SSO members in your identity provider.
- Organization members get a role on every project in the organization, so each one holds a seat on every project. Organization-wide additions are measured against the organization's plan, which is the most generous plan among its projects: with an enterprise project there is no limit, and a new project (which starts on the free plan) doesn't block the organization. These additions are adding, inviting or accepting someone into the organization, giving a billing member another role, and SSO just-in-time provisioning. They answer
402(withprojectId) when a project has no free seat under that plan. Adding someone directly to a project, or inviting them to it, is still measured against that project's own plan. Billing members take no seat. - Plans are per project and come from billing. A project created in an organization on a paid plan starts on the free plan: in this release it doesn't inherit the organization's plan, and billing is unchanged. Organization-wide additions keep using the organization's most generous project plan (above), but adding people directly to the new project, or inviting them to it, is measured against its own free plan (3 seats, counting the organization's members who hold one there) until billing upgrades it. A project whose stored plan billing doesn't define counts as free.
- Billing members can't create projects in the organization (
POST /api/projectsanswers403), and the console doesn't offer New project to someone whose only organization role is billing. - A removal first withdraws the pending invitations addressed to the person, then removes their project memberships (including any they got by accepting an invitation while the removal ran), then records the SSO just-in-time block, and only then deletes the organization membership. The response is
{ success, removedFromProjects, failedProjects }. If any step fails, the organization membership is kept and the answer is500, so you can retry. That includes the case where the SSO block can't be recorded ("Couldn't stop SSO from re-adding this member — try again"). On a self-hosted deployment that hasn't applied migration 042, the block can't be recorded at all, and removals go ahead.409"Membership changed — reload and try again" means they became an owner of an organization project while the removal ran.
Related
- Authentication & Tokens — Token types and management
- Audit Logging — Track permission changes
- REST API Reference — Team management endpoints