> ## Documentation Index
> Fetch the complete documentation index at: https://docs.oleria.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Flagsmith

> Connect your Flagsmith organization to Oleria to discover who can change your feature flags, through organization roles, RBAC roles, groups, and direct permissions, and to inventory every API key, SDK key, trust relationship, join link, and webhook.

Connect Flagsmith to Oleria to see who can change your feature flags. Oleria reads identity, access, and audit data from the Flagsmith Admin API: members, groups, organization and RBAC roles, projects and environments with their permissions, and the credentials that reach them. You can then find over-provisioned access and long-lived keys, and take action from Oleria.

This integration works with Flagsmith SaaS and with self-hosted or private cloud Flagsmith. One integration covers one Flagsmith organization.

## What Oleria discovers

* **Accounts**: every member of the organization, with name, email, last login, account creation date, and organization role. A member that SCIM has deactivated shows as disabled. MFA shows as required when your organization requires two-factor authentication, and as unavailable otherwise. SSO shows as configured when the organization has a SAML configuration. Every member shows API access, because any member can create a personal token.
* **Groups**: every group with its members and group admins. A group with an External ID is shown as synced from your identity provider. A group that new members join automatically is shown as a default group.
* **Roles**: the built-in **Organisation Administrator** and **Organisation User** roles, and every custom RBAC role with the users, groups, and organization API keys that hold it.
* **Resources**: the organization, every project, and every environment, with links to each one in the Flagsmith dashboard. Oleria doesn't import individual flags, segments, or identities. A flag has no permissions of its own: it inherits them from its project and environment.
* **Access**: who can reach each resource, and how:

  * **Organisation Administrator** holders get admin on the organization and on every project and environment.
  * RBAC roles grant permissions on the organization, projects, or environments, including tag-scoped permissions.
  * Direct user and group permissions apply on the organization, a project, or an environment.
  * A project admin is also shown as admin of each of the project's environments.

  Each access path keeps Flagsmith's permission keys, such as `VIEW_PROJECT`, `UPDATE_FEATURE_STATE`, or `ADMIN`.
* **Non-human identities and credentials**: each one is shown as a non-human identity with its credential:

  | Kind | Non-human identity type | What Oleria shows |
  | :- | :- | :- |
  | Organisation API key | `APIToken` | Name, admin or RBAC roles, creator, creation date, and expiry. |
  | Environment server-side SDK key | `APIToken` | The environment it reads, whether it is active, creation date, and expiry. |
  | OIDC trust relationship | `FederatedCredential` | Issuer, audience, claim rules, admin or RBAC roles, and creator. Requires the optional user token. |
  | Organisation join link | `APIToken` | The role it grants (**Organisation Administrator** or **Organisation User**), creation date, and expiry. |
  | Audit-log webhook | `Secret` | Whether it is enabled, and the destination host. |
  | Environment webhook | `Secret` | The environment, whether it is enabled, and the destination host. |
  | SCIM provisioning token | `APIToken` | That SCIM is configured for the organization. Enterprise plan only. |

  Oleria never reads or stores a secret value: not a key, a join link, or a webhook signing secret. Webhook addresses are reduced to their host, because the path or query can contain a token.
* **Activity**: events from the Flagsmith audit log, such as flags, segments, environments, and change requests that were created, updated, or deleted. Each event shows the member who made the change, and links to it in the Flagsmith dashboard.

Oleria refreshes this data on its [regular sync schedule](/integrations/overview.md#sync-model).

## Prerequisites

* A Flagsmith **organization administrator** account to create the organization API key.
* The Flagsmith **Scale-Up** or **Enterprise** plan for RBAC roles and audit log activity. On other plans, Oleria still syncs members, the built-in roles, projects, environments, direct permissions, and credentials.
* For self-hosted or private cloud Flagsmith, the URL of your Flagsmith API.
* Admin access to the Oleria workspace.

> [!NOTE]
>
> Self-hosted and private cloud installs must be reachable from Oleria over HTTPS at a public address. Contact [support@oleria.com](mailto:support@oleria.com) to have your instance's hostname allowed.

## Create an organization API key in Flagsmith

**1. Open API access**

Sign in to Flagsmith as an organization administrator and go to **Organisation Settings** -> **API Access**.

**2. Create an admin key**

Select **Create API Key**, give it a name, and make it an admin key. Only an admin key can read roles, groups, the audit log, and every project's and environment's permissions and keys, and run Oleria's actions. A key that holds only RBAC roles connects, but Oleria reads less with it and every action is refused.

**3. Copy the key**

Copy the key and store it securely until you've connected Oleria. If you set an expiry date, update the integration in Oleria with a new key before it expires.

### Optional: get an organization administrator user token

Flagsmith doesn't let an organization API key list or revoke organization API keys, list OIDC trust relationships, or send invites. To include them, also give Oleria the user token of an organization administrator. Without it, Oleria still finds organization API keys that hold RBAC roles, and the connection's own key. It doesn't find other admin keys or any trust relationships, and it can't revoke organization API keys or invite users.

We recommend a dedicated Flagsmith user for this, such as an `oleria-integration@yourcompany.com` account that you make an organization administrator, rather than a person's own account. Invites Oleria sends then show that user as the inviter, and the token doesn't depend on any one employee.

To get the token, sign in to Flagsmith as that organization administrator and go to **Account Settings** -> **API Keys**.

> [!WARNING]
>
> The user token acts as that user and doesn't expire. Store it as an administrative credential. If the user stops being an organization administrator, replace the token.

## Connect Flagsmith to Oleria

**1. Find Flagsmith in Oleria**

Go to your Oleria workspace, select **Integrations**, select the **Available** tab, and search for **Flagsmith**.

**2. Complete the connection form**

Select the Flagsmith card and provide the following:

| Field | Notes |
| :- | :- |
| Base URL | Optional. Leave empty for Flagsmith SaaS, which uses `https://api.flagsmith.com`. For a self-hosted or private cloud install, enter your Flagsmith API URL. The address must use `https` and can't contain credentials, a query, or a fragment. It can't be changed after you connect. |
| Organisation API key | Required. The organization API key you created in Flagsmith. |
| Organisation administrator user token | Optional. The user token of a Flagsmith organization administrator. See [Optional: get an organization administrator user token](#optional-get-an-organization-administrator-user-token). |

**3. Authenticate**

Select **Authenticate**. Oleria checks that the key belongs to exactly one Flagsmith organization and can read its members. If you entered a user token, Oleria also checks that its user is an administrator of that organization.

If **Authenticate** fails, Oleria shows the reason. The most common causes:

* Flagsmith rejects the key. Check that it's an organization API key from **Organisation Settings** -> **API Access**, and that the **Base URL** is right.
* The user token is rejected, or its user isn't an administrator of the organization. Leave the field empty, or use an administrator's token.

## Verify the integration

Confirm the Flagsmith organization appears on the **Connected** tab of your Oleria **Integrations** page. After the first sync completes, review the discovered accounts, groups, roles, resources, credentials, and activity in your Oleria workspace.

> [!NOTE]
>
> To rotate the key or the user token, edit the integration and enter the new value. To keep a stored value, leave its field empty. To stop using the user token, select **Remove the stored user token**. A key from a different Flagsmith organization is refused, and the **Base URL** is locked after you connect.

## Required permissions

An organization API key has no scopes. It is either an organization admin key or holds a set of RBAC roles, so the permissions below are Flagsmith's own role names and permission keys. The **Capabilities** tab shows the same strings.

| What Oleria does | Permission it needs |
| :- | :- |
| Read users | `Organisation API key of the connected organisation (no permission to grant)` |
| Read groups | `Organisation administrator` or `MANAGE_USER_GROUPS`. Without either, Flagsmith returns only the groups the key administers, and doesn't report an error. |
| Read roles | `Organisation administrator` |
| Read project and environment permissions, SDK keys, and webhooks | `Organisation administrator`, or administrator of each project and environment |
| Read the audit log | `Organisation administrator`, and a plan with audit logs |
| Read all organization API keys and OIDC trust relationships | `Organisation administrator user token`. An organization API key can't read them. |
| Disable user accounts (remove a member) | `Organisation administrator` |
| Create a group | `Organisation administrator` or `MANAGE_USER_GROUPS` |
| Create a user (invite) | `Organisation administrator` and the `Organisation administrator user token` |
| Add or remove a user from a group | `Organisation administrator`, `MANAGE_USER_GROUPS`, or `Group admin of the target group` |
| Add or remove a role | `Organisation administrator` |
| Revoke permission to resource instance | `Organisation administrator`, `Project administrator`, or `Environment administrator` |
| Disable NHI accounts | `Organisation administrator` or `Environment administrator`, and also the `Organisation administrator user token` for organization API keys |

Before it runs any action, Oleria checks that the organization API key is an admin key. A key that holds only `MANAGE_USER_GROUPS`, group admin, or project or environment administrator shows **Needs permission** for those actions, even though Flagsmith would accept the change, because Oleria can't read those grants for an API key.

> [!NOTE]
>
> A read row on the **Capabilities** tab shows **Needs permission** only when Flagsmith refuses the read. If another error occurs, Oleria keeps the last saved capabilities until the read works again.

## Remediation actions

| Action | Reversible? |
| :- | :- |
| **Disable user accounts** | No. Flagsmith can't suspend a member, so Oleria removes them. Removing a member also deletes their direct permissions and group memberships. To bring them back, invite them again. Oleria refuses to remove the organization's last administrator. |
| Create group | Yes. Oleria creates the group with the requested name. If a group with that name already exists, nothing changes. Reverting deletes the group Oleria created, if it still exists. |
| Create user | Partly. Flagsmith has no way to create a member directly, so Oleria emails an invite with the **Organisation User** role and any requested groups. The person becomes a member only after accepting it. If they're already a member or already invited, nothing is sent. Reverting deletes the invite while it's still pending; once accepted, use **Disable user accounts** instead. Needs the user token. |
| Add user to group / remove user from group | Yes. Adding requires the user to be a member of the organization. Reverting a removal adds the user back as a member, but doesn't restore their group admin flag. If the group is synced from your identity provider, the user's next SAML sign-in can undo the change, and the result says so. |
| Add user to role / remove user from role | Yes. For **Organisation Administrator**, adding promotes the user and removing demotes them to **Organisation User**. Every member holds one of the two, so **Organisation User** can't be added or removed directly. RBAC roles can be added to or removed from users and groups, and need the Scale-Up or Enterprise plan. Oleria refuses to demote the last administrator. Reverting restores only what Oleria changed: if the user's organization role changed since, the revert reports a conflict and leaves it. |
| **Revoke permission to resource instance** | Usually. Oleria removes a user's or group's direct permission on the organization, a project, or an environment. Access through groups, RBAC roles, or **Organisation Administrator** remains. Reverting re-creates the permission with the same permission keys and admin flag, unless a direct permission exists again. If the permission was limited to tags, the revert refuses and changes nothing, because Flagsmith's API can't restore tag limits: re-create it in Flagsmith. |
| **Disable NHI accounts** | Depends on the kind. See the next table. |

**Disable NHI accounts** works as follows for each kind:

| Kind | What Oleria does | Reversible? |
| :- | :- | :- |
| Environment server-side SDK key | Deactivates the key. | Yes. Reverting reactivates it. |
| Audit-log webhook or environment webhook | Disables the webhook. Its secret is kept. | Yes. Reverting enables it again. |
| Organisation API key | Revokes the key. Requires the user token. | No. A revoked key can't be restored. Create a new key in Flagsmith. |
| Organisation join link | Deletes the link. | No. A new link has a new secret. |
| OIDC trust relationship | Not supported. Deletion is the only way to turn it off, and that loses its issuer, audience, and claim rules. Remove it in Flagsmith. | Not applicable |
| SCIM provisioning token | Not supported. Removing the SCIM configuration is a bigger change than disabling a credential. Rotate or remove it in Flagsmith. | Not applicable |

If a server-side key or webhook is already disabled, the action succeeds without changing anything. If the target no longer exists in Flagsmith, the action fails with "not found".

Oleria never revokes the organization API key that the integration connects with. It also never removes, demotes, takes a role from, or revokes a permission of the user behind the user token.

## Known limitations

* **No per-user MFA or sign-in method.** Flagsmith shows two-factor enrollment and the sign-in method (password, Google, GitHub, or SAML) only for the signed-in user. Oleria shows MFA as required only when your organization requires two-factor authentication, and as unavailable otherwise. It shows SSO as configured, never as required. Flagsmith also doesn't record when a password was last changed.
* **No last-used time on keys.** Flagsmith doesn't record when an organization API key, SDK key, or join link was last used. It doesn't record who created SDK keys, join links, or webhooks either.
* **Limited activity.** The Flagsmith audit log records changes to flags, segments, environments, and change requests only. It has no sign-ins, and no changes to users, groups, roles, permissions, API keys, webhooks, or organization settings. It needs a plan with audit logs: on the Free plan it's empty and Oleria imports no activity. The Scale-Up plan keeps 14 days of history. When an API key makes a change, Flagsmith doesn't record which key, so the event has no actor. Flagsmith's organization audit log leaves out events that aren't tied to a project, so Oleria doesn't receive them.
* **Removing a user is permanent.** Flagsmith has no way to suspend a member through its API, so the leaver action removes them. To bring them back, invite them again.
* **Plan-dependent data.** RBAC roles need the Scale-Up or Enterprise plan. SAML is available on Scale-Up. SCIM is Enterprise only. Open-source self-hosted Flagsmith has no RBAC, SAML, or SCIM, so Oleria shows the built-in roles only and SSO as unavailable.
* **Self-hosted installs.** Enter your own **Base URL**, and contact [support@oleria.com](mailto:support@oleria.com) to have its hostname allowed, so Oleria can reach it.
* **Some keys need the user token.** Without the optional user token, Oleria doesn't find admin organization API keys other than its own, or OIDC trust relationships. It finds keys that hold RBAC roles but shows their status as unavailable, because their expiry and revocation are visible only with the token. Revoked organization API keys disappear from Flagsmith, so Oleria never shows them.
* **Some details aren't available.** Flagsmith reports when an account was created, not when it joined your organization. It doesn't return the role of a pending email invitation, so pending invitations aren't imported.
* **Third-party integration keys aren't imported.** Keys that Flagsmith stores for integrations such as Datadog or Slack aren't discovered.
* **Not yet verified against a live Flagsmith organization:** removing a user, the SCIM provisioning token, and group changes undone by a SAML sign-in.

## Contact us

For questions about this integration, contact us at [support@oleria.com](mailto:support@oleria.com).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.