Skip to content
FlagSwiftDocs

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#

Values for status
StatusDescription
pendingCreated, not yet used, and not older than 7 days.
expiredPast its expiresAt. Still listed so you can reissue it.
acceptedUsed by the person. No longer listed.
revokedRevoked, 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 values
RoleDescription
organization_adminEverything except instance settings: members and roles, environments, API keys, alerts, and every delete. Deleting anything is admin-only.
release_managerRuns 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_managerPlans 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.
developerBuilds 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.
auditorRead-only everywhere, plus the full audit log and its export.
viewerRead-only access to projects, environments, flags, metrics and releases.
system_adminEverything 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#

GET/api/roles

Returns { 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.
Request
curl -s -b "auth_session=$SESSION" "$FLAGSWIFT_URL/api/roles"
200OK
{
  "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#

POST/api/roles

Returns 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

  • namestringRequired

    1 to 40 characters, trimmed. Unique in the organization (ignoring case) and not the name or key of a built-in role.
  • descriptionstring

    Up to 200 characters. Default empty.
  • baseRolestring

    release_manager, product_manager, developer, auditor or viewer; never an administrator role. Default viewer.
  • permissionsstring[]Required

    At 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.
  • productionWriteboolean

    Allow 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).
Request
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 }'
201Created
{
  "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#

PUT/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

  • idstringRequired

    The custom role id.

Body

  • namestringRequired

    1 to 40 characters, trimmed. Unique in the organization (ignoring case) and not the name or key of a built-in role.
  • descriptionstring

    Up to 200 characters. Default empty.
  • baseRolestring

    release_manager, product_manager, developer, auditor or viewer; never an administrator role. Default viewer.
  • permissionsstring[]Required

    At 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.
  • productionWriteboolean

    Allow 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.
Request
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"] }'
200OK
{
  "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#

DELETE/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

  • idstringRequired

    The 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”.
Request
curl -s -b "auth_session=$SESSION" -X DELETE "$FLAGSWIFT_URL/api/roles/ROLE_ID"
200OK
{ "status": "success", "message": "Role deleted", "data": null }

Members#

List members#

GET/api/members

The 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.
Request
curl -s -b "auth_session=$SESSION" "$FLAGSWIFT_URL/api/members"
200OK
{
  "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#

PATCH/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

  • idstringRequired

    The membership id (the id field of a member, not userId).

Body

  • rolestringRequired

    One 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 is system_admin and you are not a system admin.
  • 404“Member not found”.
  • 409“This is the last administrator”.
Request
curl -s -b "auth_session=$SESSION" -X PATCH "$FLAGSWIFT_URL/api/members/MEMBERSHIP_ID" \
  -H "Content-Type: application/json" \
  -d '{ "role": "release_manager" }'
200OK
{ "status": "success", "message": "Role updated successfully", "data": { "id": "MEMBERSHIP_ID", "role": "release_manager" } }

Reset a member's password#

POST/api/members/{id}/reset-password

Generates 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

  • idstringRequired

    The 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”.
Request
curl -s -b "auth_session=$SESSION" -X POST "$FLAGSWIFT_URL/api/members/MEMBERSHIP_ID/reset-password"
200OK
{
  "status": "success",
  "message": "Password reset",
  "data": { "name": "Tunde Bello", "email": "tunde@example.com", "temporaryPassword": "Qm7-xT2p-Lw9c-Rv4h" }
}

Remove a member#

DELETE/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

  • idstringRequired

    The 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”.
Request
curl -s -b "auth_session=$SESSION" -X DELETE "$FLAGSWIFT_URL/api/members/MEMBERSHIP_ID"
200OK
{ "status": "success", "message": "Member removed successfully", "data": null }

Transfer ownership#

POST/api/members/{id}/transfer-ownership

Makes 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

  • idstringRequired

    The 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.
Request
curl -s -b "auth_session=$SESSION" -X POST "$FLAGSWIFT_URL/api/members/MEMBERSHIP_ID/transfer-ownership"
200OK
{ "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#

POST/api/invitations

Authorization

members.invite

Body

  • namestringRequired

    The person's full name, up to 80 characters, trimmed.
  • emailstringRequired

    A valid email address. Trimmed and stored in lower case.
  • rolestringRequired

    A 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 a system_admin.
  • 409“This person is already a member”, or “This email already belongs to another organization”.
Request
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" }'
201Created
{
  "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#

POST/api/invitations/bulk

One 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

  • rolestringRequired

    One role for everyone: a built-in role value or custom:<id>.
  • invitees{ name, email }[]Required

    1 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.
Request
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" }
    ]
  }'
201Created
{
  "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#

GET/api/invitations

A 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.
Request
curl -s -b "auth_session=$SESSION" "$FLAGSWIFT_URL/api/invitations"
200OK
{
  "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#

POST/api/invitations/{id}/reissue

Replaces 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

  • idstringRequired

    The 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.
Request
curl -s -b "auth_session=$SESSION" -X POST "$FLAGSWIFT_URL/api/invitations/INVITATION_ID/reissue"
200OK
{
  "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#

DELETE/api/invitations/{id}

Authorization

members.invite

Path parameters

  • idstringRequired

    The 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”.
Request
curl -s -b "auth_session=$SESSION" -X DELETE "$FLAGSWIFT_URL/api/invitations/INVITATION_ID"
200OK
{ "status": "success", "message": "Invitation revoked", "data": null }

Acceptance is a public call

The person who receives the link accepts it without a session. See Authentication.
  • Responses that carry links or passwords are marked Cache-Control: no-store.

Common patterns#

Create a custom role, invite someone into it#

bash
# 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"}'
bash
# 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.

bash
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"