Members and invitations
Who is in the organization, what role they hold, and how new people join.
Concepts#
Which id goes where#
A member has two ids. id is the membership, and is what /api/members/{id} takes. userId is the person, and is what the release proposer filter and reviewerId take. Both come from the members list.
Invitation lifecycle#
| Status | Description |
|---|---|
| pending | Created, not yet used, and not older than 7 days. |
| expired | Past its expiresAt. Still listed so you can reissue it. |
| accepted | Used by the person. No longer listed. |
| revoked | Revoked, or replaced by a newer invitation for the same address. No longer listed. |
- Only the hash of the link is stored, so the link is returned once, when you create or reissue the invitation. To get a link again, reissue.
- Inviting an address that already has an open invitation replaces it: the old link stops working and only the newest one is valid.
- Reissuing kills the old link and the old one-time password, and starts a fresh 7 days.
- A person who accepts is signed in, joins with the invited role, and any session they had elsewhere ends.
- Each create and reissue also returns a one-time
temporaryPassword. If the link cannot be delivered, the person can sign in with their email and that password to accept the invitation instead. Treat it like the link.
Rules that protect the organization#
- The owner cannot be changed or removed. Transfer ownership first.
- Only the owner can make someone an administrator, or change or remove one. Only a system admin can grant or change
system_admin. - The last administrator cannot be demoted or removed (
409). - A removed member loses access at once and is detached from the organization.
Roles#
Ownership is not a role: one admin is marked as the organization's owner, and only the owner can transfer ownership, reset an admin's password or remove an admin. Every other person holds one built-in role or one of your own custom roles.
| Role | Description |
|---|---|
| organization_admin | Everything except instance settings: members and roles, environments, API keys, alerts, and every delete. Deleting anything is admin-only. |
| release_manager | Runs releases: flags, rollouts, targeting and segments in every environment including production, the kill switch and restore, approves or rejects releases, manages alerts. Cannot delete. |
| product_manager | Plans what ships, but does not apply it. Creates and edits flags, targeting and segments and proposes releases, with no toggles, rollouts, rollbacks or kill switch, and no targeting changes in production. |
| developer | Builds with flags: create, edit, toggle, archive, roll out, target and propose releases. Read-only for toggles, rollouts, targeting and the kill switch in production. Sees the audit events for their own actions. |
| auditor | Read-only everywhere, plus the full audit log and its export. |
| viewer | Read-only access to projects, environments, flags, metrics and releases. |
| system_admin | Everything an admin can do, plus the instance-level permissions (system.read, system.manage) that organization_admin lacks. It can act as the owner when appointing or removing admins. Only a system admin can grant it or change someone who holds it, and the console role pickers show it only to system admins. |
| custom:{id} | A role your organization defined (see Custom roles). Use this form wherever a role is accepted. |
Custom roles#
A custom role is a named set of permissions on top of a built-in base role. The base role (never an admin role) decides what the role can do in the console that permissions do not cover; the permission list decides the rest. A role can hold any permission except those that stay with the built-in roles: organization.deactivate and system.* (owner and system admins), and members.invite, members.update, members.remove, roles.manage and every delete permission (flags.delete, projects.delete, environments.delete, targeting.delete, segments.delete), which belong to admins. A role saved before this rule loses such permissions at once. The person creating or editing a role can only grant permissions they hold themselves, and matching read permissions are added automatically (a role that can toggle flags can also view them). Production changes are blocked for a custom role unless productionWrite is true.
List roles#
/api/rolesReturns { builtIn, custom, limit }: each built-in role with its permissions, production restrictions and member count, and each custom role with its ref (custom:<id>), base role, permissions and member count.
Authorization
roles.read
Errors
- 401No session, or it has expired (“Authentication required”).
- 403Your role lacks
roles.read.
curl -s -b "auth_session=$SESSION" "$FLAGSWIFT_URL/api/roles"{
"status": "success",
"message": "Roles fetched successfully",
"data": {
"builtIn": [
{
"kind": "built_in",
"key": "developer",
"label": "Developer",
"description": "Builds with flags ...",
"permissions": ["flags.read", "flags.create", "flags.toggle"],
"productionRestricted": ["flags.toggle"],
"members": 4
}
],
"custom": [
{
"kind": "custom",
"id": "ROLE_ID",
"ref": "custom:ROLE_ID",
"name": "QA lead",
"description": "",
"baseRole": "developer",
"permissions": ["flags.read", "flags.toggle", "releases.read", "releases.create", "organization.read", "projects.read", "environments.read"],
"productionWrite": false,
"members": 0,
"createdByEmail": "admin@example.com",
"updatedAt": "2026-10-03T09:00:00.000Z"
}
],
"limit": 25
}
}Create a role#
/api/rolesReturns 201 with the role. At most 25 custom roles per organization. The response shows the permissions the role really holds: reads are added automatically, as in the example.
Authorization
roles.manage
Body
namestringRequired1 to 40 characters, trimmed. Unique in the organization (ignoring case) and not the name or key of a built-in role.descriptionstringUp to 200 characters. Default empty.baseRolestringrelease_manager, product_manager, developer, auditor or viewer; never an administrator role. Default viewer.permissionsstring[]RequiredAt least one permission, such as flags.toggle or audit.read. Unknown permissions, and the ones a custom role may never hold (<C>organization.deactivate</C>, <C>system.*</C>, member management, <C>roles.manage</C> and the delete permissions), are rejected. Each must be one you hold yourself. Matching reads are added for you.productionWritebooleanAllow changes in production environments. Default false. You can only allow it if you can make those changes yourself.
Errors
- 400“Give the role a name”, “Keep the name under 40 characters”, “Keep the description under 200 characters”, “Choose a base role” (it must not be an administrator role), “Choose at least one permission”, “Unknown permission”, “A custom role cannot hold …” for a permission that stays with admins or the owner, “You can't give a role permissions you don't hold yourself”, or a production change you cannot make yourself.
- 401No session, or it has expired (“Authentication required”).
- 403Your role lacks
roles.manage, the organization is deactivated, or the request was blocked as cross-site. - 40925 custom roles already exist, the name belongs to a built-in role, or another role has that name (compared without regard to case).
curl -s -b "auth_session=$SESSION" -X POST "$FLAGSWIFT_URL/api/roles" \
-H "Content-Type: application/json" \
-d '{ "name": "QA lead", "baseRole": "developer", "permissions": ["flags.read", "flags.toggle", "releases.create"], "productionWrite": false }'{
"status": "success",
"message": "Role created",
"data": {
"kind": "custom",
"id": "ROLE_ID",
"ref": "custom:ROLE_ID",
"name": "QA lead",
"description": "",
"baseRole": "developer",
"permissions": ["flags.read", "flags.toggle", "releases.read", "releases.create", "organization.read", "projects.read", "environments.read"],
"productionWrite": false,
"members": 0,
"createdByEmail": "admin@example.com",
"updatedAt": "2026-10-03T09:00:00.000Z"
}
}Change a role#
/api/roles/{id}Takes the same body as create and replaces the role: send every field, not only what changes. People on the role get the new permissions straight away; their sessions are refreshed.
Authorization
roles.manage
Path parameters
idstringRequiredThe custom role id.
Body
namestringRequired1 to 40 characters, trimmed. Unique in the organization (ignoring case) and not the name or key of a built-in role.descriptionstringUp to 200 characters. Default empty.baseRolestringrelease_manager, product_manager, developer, auditor or viewer; never an administrator role. Default viewer.permissionsstring[]RequiredAt least one permission, such as flags.toggle or audit.read. Unknown permissions, and the ones a custom role may never hold (<C>organization.deactivate</C>, <C>system.*</C>, member management, <C>roles.manage</C> and the delete permissions), are rejected. Each must be one you hold yourself. Matching reads are added for you.productionWritebooleanAllow changes in production environments. Default false. You can only allow it if you can make those changes yourself.
Errors
- 400The same validation errors as create.
- 401No session, or it has expired (“Authentication required”).
- 403Your role lacks
roles.manage, the organization is deactivated, or the request was blocked as cross-site. - 404“Role not found”.
- 409The new name is a built-in role name or is used by another role.
curl -s -b "auth_session=$SESSION" -X PUT "$FLAGSWIFT_URL/api/roles/ROLE_ID" \
-H "Content-Type: application/json" \
-d '{ "name": "QA lead", "baseRole": "developer", "permissions": ["flags.read", "flags.toggle", "releases.create", "audit.read"] }'{
"status": "success",
"message": "Role saved",
"data": {
"kind": "custom",
"id": "ROLE_ID",
"ref": "custom:ROLE_ID",
"name": "QA lead",
"description": "",
"baseRole": "developer",
"permissions": ["flags.read", "flags.toggle", "releases.read", "releases.create", "organization.read", "projects.read", "environments.read"],
"productionWrite": false,
"members": 0,
"createdByEmail": "admin@example.com",
"updatedAt": "2026-10-03T09:00:00.000Z"
}
}Delete a role#
/api/roles/{id}Refused with 409 while anyone holds the role or an open invitation uses it; move people to another role first. If a role is removed some other way, its members fall back to Viewer rather than gaining access.
Authorization
roles.manage
Path parameters
idstringRequiredThe custom role id.
Errors
- 401No session, or it has expired (“Authentication required”).
- 403Your role lacks
roles.manage, the organization is deactivated, or the request was blocked as cross-site. - 404“Role not found”.
- 409“2 people have this role. Move them to another role first”, or “Open invitations still use this role. Revoke them first”.
curl -s -b "auth_session=$SESSION" -X DELETE "$FLAGSWIFT_URL/api/roles/ROLE_ID"{ "status": "success", "message": "Role deleted", "data": null }Members#
List members#
/api/membersThe reply is a plain array, oldest first, with no paging. role is the built-in role, or the base role of a custom one; roleLabel is what to show, and customRoleId is set for custom roles.
Authorization
members.read
Errors
- 401No session, or it has expired (“Authentication required”).
- 403Your role lacks
members.read.
curl -s -b "auth_session=$SESSION" "$FLAGSWIFT_URL/api/members"{
"status": "success",
"message": "OK",
"data": [
{
"id": "MEMBERSHIP_ID",
"userId": "USER_ID",
"name": "Grace Eze",
"email": "grace@example.com",
"role": "organization_admin",
"roleLabel": "Admin",
"customRoleId": null,
"isOwner": true,
"createdAt": "2026-08-01T10:00:00.000Z"
},
{
"id": "MEMBERSHIP_ID_2",
"userId": "USER_ID_2",
"name": "Tunde Bello",
"email": "tunde@example.com",
"role": "developer",
"roleLabel": "QA lead",
"customRoleId": "ROLE_ID",
"isOwner": false,
"createdAt": "2026-09-02T12:30:00.000Z"
}
]
}Change a role#
/api/members/{id}role is a built-in role value or custom:<id>. Only the owner can make someone an administrator, and only a system admin can grant system_admin.
Returns { id, role }, where role is the base role. Sending the role the member already has changes nothing. The member's session is refreshed and they are emailed. The change is audited as member.role_changed.
Authorization
members.update
Path parameters
idstringRequiredThe membership id (the id field of a member, not userId).
Body
rolestringRequiredOne of organization_admin, release_manager, product_manager, developer, auditor, viewer, system_admin, or custom:<id> for a custom role (id of letters, digits, _ or -, up to 64 characters). Only the owner may assign organization_admin and only a system admin system_admin.
Errors
- 400“Role is required”, “Choose a role” for a value that is not a built-in role or
custom:<id>, or “Unknown role” for a custom role that does not exist. - 401No session, or it has expired (“Authentication required”).
- 403You lack
members.update; the member is the owner (“The owner can't be changed or removed”); you are not the owner and the target or the new role is administrator; or the new role issystem_adminand you are not a system admin. - 404“Member not found”.
- 409“This is the last administrator”.
curl -s -b "auth_session=$SESSION" -X PATCH "$FLAGSWIFT_URL/api/members/MEMBERSHIP_ID" \
-H "Content-Type: application/json" \
-d '{ "role": "release_manager" }'{ "status": "success", "message": "Role updated successfully", "data": { "id": "MEMBERSHIP_ID", "role": "release_manager" } }Reset a member's password#
/api/members/{id}/reset-passwordGenerates a new password and returns it once, as { name, email, temporaryPassword }, for you to pass on. The old password stops working and the member is signed out everywhere. The response is not cached and the password cannot be shown again. It follows the same rules as changing a role: nobody resets the owner, only the owner resets an admin, and you reset your own with Change password instead.
Authorization
members.update
Path parameters
idstringRequiredThe membership id. Not your own.
Errors
- 400“Use Change password for your own account”.
- 401No session, or it has expired (“Authentication required”).
- 403You lack
members.update, the member is the owner, or the member is an administrator and you are not the owner. - 404“Member not found”.
curl -s -b "auth_session=$SESSION" -X POST "$FLAGSWIFT_URL/api/members/MEMBERSHIP_ID/reset-password"{
"status": "success",
"message": "Password reset",
"data": { "name": "Tunde Bello", "email": "tunde@example.com", "temporaryPassword": "Qm7-xT2p-Lw9c-Rv4h" }
}Remove a member#
/api/members/{id}Removes the person from the organization and ends their sessions. Their past activity stays in the audit log.
Authorization
members.remove
Path parameters
idstringRequiredThe membership id.
Errors
- 401No session, or it has expired (“Authentication required”).
- 403You lack
members.remove, the member is the owner, or the member is an administrator and you are not the owner. - 404“Member not found”.
- 409“This is the last administrator”.
curl -s -b "auth_session=$SESSION" -X DELETE "$FLAGSWIFT_URL/api/members/MEMBERSHIP_ID"{ "status": "success", "message": "Member removed successfully", "data": null }Transfer ownership#
/api/members/{id}/transfer-ownershipMakes another administrator the owner. The previous owner stays an administrator. Only the owner can deactivate or reactivate the organization, so this is how that duty moves.
Authorization
members.update
Path parameters
idstringRequiredThe membership id of an administrator other than you.
Errors
- 401No session, or it has expired (“Authentication required”).
- 403“Only the owner can transfer ownership”, “You are already the owner”, or “Ownership can only go to an administrator. Make them an administrator first”.
- 404“Member not found”.
- 409“Ownership changed while you were transferring it”: someone else moved it first. Refresh and try again.
curl -s -b "auth_session=$SESSION" -X POST "$FLAGSWIFT_URL/api/members/MEMBERSHIP_ID/transfer-ownership"{ "status": "success", "message": "Ownership transferred", "data": null }Invitations#
An invitation is a single-use link for one email address and role, valid for 7 days. The link is returned when you create or reissue it, and nowhere else. If an email provider (Resend or SMTP) is configured the server also emails it; the response says whether that worked in emailed (with emailError when sending failed), and a failed email never fails the call.
Invite one person#
/api/invitationsAuthorization
members.invite
Body
namestringRequiredThe person's full name, up to 80 characters, trimmed.emailstringRequiredA valid email address. Trimmed and stored in lower case.rolestringRequiredA built-in role value or custom:<id>, as in Change a role. Only the owner can invite an administrator.
Errors
- 400“Full name is required” (or over 80 characters), “Enter a valid email address”, “Email address is required”, “Role is required” or “Choose a role”, or “Unknown role” for a custom role that does not exist.
- 401No session, or it has expired (“Authentication required”).
- 403You lack
members.invite, the organization is deactivated, the request was blocked as cross-site, or you cannot hand out that role: only the owner can invite an administrator and only a system admin can invite asystem_admin. - 409“This person is already a member”, or “This email already belongs to another organization”.
curl -s -b "auth_session=$SESSION" -X POST "$FLAGSWIFT_URL/api/invitations" \
-H "Content-Type: application/json" \
-d '{ "name": "Ada Obi", "email": "ada@example.com", "role": "developer" }'{
"status": "success",
"message": "Invitation created",
"data": {
"invitation": {
"id": "c47d1e90-3b2a-4a6f-9e11-0f8b52d7a3c4",
"name": "Ada Obi",
"email": "ada@example.com",
"role": "developer",
"roleLabel": "Developer",
"customRoleId": null,
"status": "pending",
"invitedByEmail": "admin@example.com",
"createdAt": "2026-10-03T09:00:00.000Z",
"expiresAt": "2026-10-10T09:00:00.000Z"
},
"inviteUrl": "https://flags.example.com/invite/INVITE_TOKEN",
"temporaryPassword": "Hv3-kP8s-Zt5n-Wd2b",
"emailed": true
}
}Invite many people#
/api/invitations/bulkOne role for up to 50 people. Each address succeeds or fails on its own, so one bad address does not stop the rest. The call answers 201 even when some rows failed: check failed and each row's ok.
Returns created, failed and a results list in the order you sent. Each entry has ok, name and email; successes add the invitation, an inviteUrl, a temporaryPassword and emailed, failures an error message such as “This person is already a member”.
Authorization
members.invite
Body
rolestringRequiredOne role for everyone: a built-in role value or custom:<id>.invitees{ name, email }[]Required1 to 50 people. Each needs a name (up to 80 characters) and a valid email address.
Errors
- 400The request itself is invalid, so nothing is created: “Add at least one email address”, “Invite up to 50 people at a time”, a bad email or an over-long name on any row, or a bad or unknown role.
- 401No session, or it has expired (“Authentication required”).
- 403You lack
members.invite, you cannot hand out that role, the organization is deactivated, or the request was blocked as cross-site.
curl -s -b "auth_session=$SESSION" -X POST "$FLAGSWIFT_URL/api/invitations/bulk" \
-H "Content-Type: application/json" \
-d '{
"role": "developer",
"invitees": [
{ "name": "Ada Obi", "email": "ada@example.com" },
{ "name": "Grace Eze", "email": "grace@example.com" }
]
}'{
"status": "success",
"message": "1 invitation created",
"data": {
"results": [
{
"ok": true,
"name": "Ada Obi",
"email": "ada@example.com",
"invitation": {
"id": "c47d1e90-3b2a-4a6f-9e11-0f8b52d7a3c4",
"name": "Ada Obi",
"email": "ada@example.com",
"role": "developer",
"roleLabel": "Developer",
"customRoleId": null,
"status": "pending",
"invitedByEmail": "admin@example.com",
"createdAt": "2026-10-03T09:00:00.000Z",
"expiresAt": "2026-10-10T09:00:00.000Z"
},
"inviteUrl": "https://flags.example.com/invite/INVITE_TOKEN",
"temporaryPassword": "Hv3-kP8s-Zt5n-Wd2b",
"emailed": true
},
{ "ok": false, "name": "Grace Eze", "email": "grace@example.com", "error": "This person is already a member" }
],
"created": 1,
"failed": 1
}
}List open invitations#
/api/invitationsA plain array, newest first, with no paging. Only pending and expired invitations are listed, and never the link.
Authorization
members.invite
Errors
- 401No session, or it has expired (“Authentication required”).
- 403Your role lacks
members.invite, the organization is deactivated, or the request was blocked as cross-site.
curl -s -b "auth_session=$SESSION" "$FLAGSWIFT_URL/api/invitations"{
"status": "success",
"message": "OK",
"data": [
{
"id": "c47d1e90-3b2a-4a6f-9e11-0f8b52d7a3c4",
"name": "Ada Obi",
"email": "ada@example.com",
"role": "developer",
"roleLabel": "Developer",
"customRoleId": null,
"status": "pending",
"invitedByEmail": "admin@example.com",
"createdAt": "2026-10-03T09:00:00.000Z",
"expiresAt": "2026-10-10T09:00:00.000Z"
}
]
}Reissue a link#
/api/invitations/{id}/reissueReplaces the old link with a new one, valid for a fresh period, and emails it again when SMTP is set up.
Authorization
members.invite
Path parameters
idstringRequiredThe invitation id. It must be pending or expired.
Errors
- 401No session, or it has expired (“Authentication required”).
- 403Your role lacks
members.invite, the organization is deactivated, or the request was blocked as cross-site. - 404No such invitation in your organization.
- 409“This invitation has already been used or revoked”, or the person has since become a member or joined another organization.
curl -s -b "auth_session=$SESSION" -X POST "$FLAGSWIFT_URL/api/invitations/INVITATION_ID/reissue"{
"status": "success",
"message": "New invitation link created",
"data": {
"invitation": {
"id": "c47d1e90-3b2a-4a6f-9e11-0f8b52d7a3c4",
"name": "Ada Obi",
"email": "ada@example.com",
"role": "developer",
"roleLabel": "Developer",
"customRoleId": null,
"status": "pending",
"invitedByEmail": "admin@example.com",
"createdAt": "2026-10-03T09:00:00.000Z",
"expiresAt": "2026-10-10T09:00:00.000Z"
},
"inviteUrl": "https://flags.example.com/invite/NEW_INVITE_TOKEN",
"temporaryPassword": "Bk6-nV2q-Ys8m-Tc4j",
"emailed": false
}
}Revoke an invitation#
/api/invitations/{id}Authorization
members.invite
Path parameters
idstringRequiredThe invitation id. It must be pending or expired.
Errors
- 401No session, or it has expired (“Authentication required”).
- 403Your role lacks
members.invite, the organization is deactivated, or the request was blocked as cross-site. - 404No such invitation in your organization.
- 409“This invitation has already been used or revoked”.
curl -s -b "auth_session=$SESSION" -X DELETE "$FLAGSWIFT_URL/api/invitations/INVITATION_ID"{ "status": "success", "message": "Invitation revoked", "data": null }Acceptance is a public call
- Responses that carry links or passwords are marked
Cache-Control: no-store.
Common patterns#
Create a custom role, invite someone into it#
# 1. Create the role and keep data.ref (custom:ROLE_ID)
curl -s -b "auth_session=$SESSION" -X POST "$FLAGSWIFT_URL/api/roles" \
-H "Content-Type: application/json" \
-d '{"name":"QA lead","baseRole":"developer","permissions":["flags.read","flags.toggle","releases.create"]}'
# 2. Invite with that ref wherever a role is accepted
curl -s -b "auth_session=$SESSION" -X POST "$FLAGSWIFT_URL/api/invitations" \
-H "Content-Type: application/json" \
-d '{"name":"Ada Obi","email":"ada@example.com","role":"custom:ROLE_ID"}'The invitee lost the link#
# Find the invitation id, then reissue: the old link stops working
curl -s -b "auth_session=$SESSION" "$FLAGSWIFT_URL/api/invitations" | jq '.data[] | {id, email, status}'
curl -s -b "auth_session=$SESSION" -X POST "$FLAGSWIFT_URL/api/invitations/INVITATION_ID/reissue" | jq -r '.data.inviteUrl'Offboard an administrator#
Only the owner can remove an administrator. Find the membership id, then remove it. If the departing person is the owner, transfer ownership to another administrator first.
curl -s -b "auth_session=$SESSION" "$FLAGSWIFT_URL/api/members" | jq '.data[] | select(.email=="old@example.com") | .id'
curl -s -b "auth_session=$SESSION" -X DELETE "$FLAGSWIFT_URL/api/members/MEMBERSHIP_ID"