Before the Organisation makes sense, two smaller ideas need a clear definition: the feature flag, and the platform that stores it.

First, what is a feature flag?

A feature flag (also called a feature toggle) is an on and off switch placed inside software. The code for a new feature is already deployed to the servers, but the flag decides whether real users can see it. Turn the flag on and the feature appears. Turn it off and it vanishes, with no new deployment needed. Teams use flags to release slowly to a small group, to test ideas, to hide unfinished work, and to shut off a misbehaving feature in seconds.

Second, what is Flagsmith?

Flagsmith is a feature flag and remote configuration service. It gives you a dashboard where people create and control flags, plus a set of SDKs (small libraries that your applications install) which ask Flagsmith what each flag should be right now. It is open source, so a company can run it on its own servers, and it is also offered as a hosted cloud service where Flagsmith runs it for you. Whichever way it is deployed, the building blocks inside are the same.

Third, what is an Organisation?

An Organisation is the outermost container in Flagsmith. Everything else lives inside it. Your people (called members) belong to an Organisation. Your Projects belong to an Organisation. Your groups, your roles, your integration settings, your usage numbers and your subscription plan are all attached to an Organisation. When you sign up for the first time, Flagsmith asks you to create one, because nothing else can exist without it.

The spelling matters only a little, but you will see it in the product: Flagsmith uses the British spelling, “Organisation”, in its dashboard. In this guide the same spelling is used so it matches what you see on screen.

An important detail for newcomers: a single person can belong to more than one Organisation using the same login. A freelance developer might be a member of a client’s Organisation and also own a personal one. Switching between them is done from the dashboard, and nothing leaks across, because each Organisation is a fully separate space.

A flag on its own is trivial. Ten thousand flags owned by two hundred people is a management problem, and the Organisation exists to solve it.

The problem it solves

In the early days of a startup, one developer creates a handful of flags and everybody knows what they do. As the company grows, three things go wrong at the same time. The number of flags explodes. The number of people who touch them multiplies. And the cost of a mistake rises, because a wrong flip now affects millions of users rather than a few friends testing the app.

Without a top-level container, there is no answer to simple governance questions. Who is allowed to create a new product space? Who can invite a contractor? When the contractor leaves, who removes them from every place at once? Who receives the invoice? An Organisation gives each of these questions exactly one home.

How big companies think about this

Large engineering companies learned this lesson long ago. Amazon is widely known for organising work around small teams that each own a service from end to end, often described by the “two pizza team” idea (a team small enough to be fed by two pizzas). Netflix is known for giving teams freedom while keeping shared guard rails. In both styles, teams need autonomy over their own product, while the company needs one place to keep identity, safety rules and cost under control. Flagsmith maps this directly: each team gets its own Project, and the Organisation above them keeps the rules and the bill.

This is also why the Organisation is not optional or hidden. It is the first thing you create and the first screen that explains how everything else fits together.

Flagsmith is built as a tree with three main levels. Understanding the tree is the key to understanding every setting in the product.

At the root is the Organisation. Directly below it are Projects. Below each Project are Environments. At the bottom, inside each Environment, are the actual flag values and the end users (called identities) whose flags are being evaluated. The diagram below shows a fictional company called Acme Corp using Flagsmith.

graph TD
  ORG["Organisation: Acme Corp"] --> P1["Project: Checkout Service"]
  ORG --> P2["Project: Mobile App"]
  ORG --> MEM["Members, Groups and Roles"]
  ORG --> BILL["Plan, Usage and Billing"]
  P1 --> E1["Environment: Development"]
  P1 --> E2["Environment: Staging"]
  P1 --> E3["Environment: Production"]
  P1 --> SEG["Segments and Tags"]
  E3 --> FS["Feature states and values"]
  E3 --> IDN["Identities and traits"]
  E3 --> KEY["Environment API keys"]
    

What each level is for

A detail that surprises many beginners

A feature is defined once at the Project level, but its value is stored separately for each Environment. So the feature called “new checkout page” exists once in the Checkout Project, yet it can be on in Development, on for ten percent of users in Staging, and off in Production. This split is what makes safe, step by step releases possible. The Organisation does not hold flags at all. It holds the people and rules that decide who may touch the Projects that do.

Open the Organisation settings page and you will find a surprisingly rich set of controls. Here is a tour of the main parts.

Notice a pattern: everything in this list is about who, how much and under what rules. None of it is about whether a particular button on a website is green or blue. That decision lives lower in the tree. This clean separation between management of people and management of features is one of the best design choices in the product, because it lets a security team and a product team work in the same system without stepping on each other.

A tool is only as safe as the list of people who can open it. Flagsmith keeps that list at the Organisation level.

What is a member?

A member (sometimes called a user) is a person who has an account in Flagsmith and has been added to your Organisation. The same person can be a member of several Organisations. Each membership carries its own level of power, so someone might be an administrator in one Organisation and a read-only observer in another.

How people join

Joining is done by invitation. An administrator types an email address, chooses what level of access the new person should start with, and Flagsmith sends a message with a link. The person clicks the link, creates a password or signs in with an existing identity provider, and lands inside the Organisation. Flagsmith also supports shareable invitation links, which are handy when onboarding a whole team at once, although such links should be treated like a spare key: short-lived, and removed when no longer needed.

What is a seat?

A seat is one place for one human in your plan. Paid plans usually allow a certain number of seats, and the member count in your Organisation is compared against that limit. This is one reason to clean up your member list regularly. A former contractor who is still a member is both a security risk and, on some plans, a wasted seat.

Questions new administrators often ask

Should I invite people one by one or in bulk? Invite in small batches, one team at a time. That way you can place each new member into the right group straight away, instead of leaving a crowd of members with no permissions and no clear owner.

What if someone changes teams? Move them between groups. Their membership in the Organisation stays the same, but their reach changes in one step. This is much safer than removing and re-inviting them, which can leave a gap in which work is blocked.

What if a person has two jobs? Put them in both groups. Permissions are combined, so they receive the sum of what both groups allow. Review such double memberships regularly, because they are where over-wide access hides.

Giving permissions to individuals does not scale. Groups and roles are the tools that make access manageable when a company grows.

What is a user group?

A user group is a named collection of members. Instead of saying “Priya, Marcus and Aiko may edit flags in the Payments Project”, you say “the Payments Team group may edit flags in the Payments Project”, and then you simply keep the group membership up to date. When a new engineer joins the team, adding them to the group is the only step needed.

What is Role Based Access Control?

Role Based Access Control, usually shortened to RBAC, is the idea that permissions are bundled into named roles, and people receive roles rather than raw permissions. A role such as “Release Manager” might include the right to change flag values in production and approve change requests, but not the right to delete a Project. In Flagsmith, custom roles are a feature of the higher paid plans, while the basic ideas of administrator and ordinary user are available more widely. Always check the current plan details in your account, because the exact split between plans can change over time.

Why this matters at scale

Consider a company with forty engineering teams. If every permission is set per person, the access list becomes thousands of small decisions that nobody can audit. With groups, the same company has forty groups and a few standard roles. An auditor can read the list in minutes, and an engineer changing teams only needs one membership change. Large technology companies such as Google and Uber have written publicly about the need for structured access control at scale, and the same principle applies, in a smaller form, to any company using Flagsmith.

Permissions in Flagsmith are layered, following the same three levels as the tree itself. Power given at a higher level flows downward.

There are three layers of permission, each matching one level of the hierarchy. At the Organisation level, permissions answer broad questions, such as whether a person may create new Projects or manage other members. At the Project level, permissions control things such as viewing the Project, creating features, managing segments and viewing the audit log. At the Environment level, permissions control the most sensitive actions, such as changing a feature’s state, managing identities and approving changes.

flowchart TD
  U["A member tries an action"] --> A{"Is the member an Organisation administrator?"}
  A -- Yes --> OK["Allowed"]
  A -- No --> B{"Does a Project permission cover it?"}
  B -- Yes --> OK
  B -- No --> C{"Does an Environment permission cover it?"}
  C -- Yes --> OK
  C -- No --> D["Denied"]
    

The picture above is intentionally simplified. In real use, permissions can arrive from several places at once: directly granted to the person, inherited through a group, or granted by a role. Flagsmith combines them, so a person ends up with the sum of what they have been given. The safe habit is to grant through groups and roles, and to keep direct grants rare, because direct grants are the easiest to forget.

Least privilege: the guiding rule

The principle of least privilege says every person should have only the power they need for their job, and no more. In Flagsmith this usually means that many engineers can edit flags in Development, fewer can edit in Staging, and only a small, named group can edit in Production. The widest permission is given where mistakes are cheapest, and the narrowest where mistakes are costly.

Security rules that must apply to everyone belong at the top of the tree. This is where they are set.

Sign-in methods

Flagsmith supports ordinary email and password sign-in, and sign-in through popular identity services. Larger plans add single sign-on, often shortened to SSO. With SSO, people log in through the company’s own identity system, the same one they use for email and internal tools. The big benefit is control: when the identity system says a person no longer works at the company, their access to Flagsmith ends as well. A common standard behind SSO is SAML, a way for two systems to trust each other and pass along a signed statement saying who a person is.

Two-step verification

Two-step verification (also called two-factor authentication or 2FA) asks for a password plus a second proof, such as a code from a phone app. Flagsmith lets an Organisation encourage or require this, so a stolen password alone is not enough to get in. For a platform that can switch off features for every customer, this extra step is strongly recommended.

Limiting who can create Projects

Many Organisations choose to restrict Project creation to administrators. This prevents a situation where fifty people each create their own experimental Project and nobody remembers which is the real one. The rule is small, but it keeps the tree tidy.

Automated user management

At the top tier, companies often want their identity system to create and remove Flagsmith users automatically, with no human clicking. This is called provisioning. Availability depends on your plan and your Flagsmith version, so it is wise to confirm the current options in the official documentation before promising it to your security team.

Choosing among the security options

Not every company needs every control on day one, and piling on rules too early can frustrate teams and push them to find risky shortcuts. A practical order is as follows. Begin with two-step verification, because it is cheap and blocks the most common attack. Add a limit on who can create Projects as soon as more than one team is involved. Introduce single sign-on when the member list is large enough that manual offboarding becomes unreliable. Add approval flows when a mistake in Production would cause real financial or reputational harm. Each step answers a specific pain, and each is easier to adopt when the team can see why it exists.

A final reminder is that security settings are only as strong as the people who understand them. A five minute explanation of why two-step verification matters, delivered kindly at the start, prevents far more resentment than a sudden announcement that everyone must comply by Friday.

Flagsmith uses several kinds of keys. Mixing them up is one of the most common and most costly mistakes, so it is worth learning the differences carefully.

What is an API key?

An API key is a secret string of characters that proves “this request is allowed”. Machines use keys the way people use passwords. Flagsmith has keys at two different levels, and they do completely different jobs.

The golden rule

Never place a secret key where the public can read it. A client-side key is meant for the front of the house, so exposure is expected. A server-side key or an Organisation key found in a public website’s source or in a public code repository is an emergency. Rotate it, meaning create a new one and delete the old one, at once.

The life of a key

Keys are not permanent. A healthy key has a short biography: it is created for a purpose, named so that people know what it is for, stored in exactly one safe place, used, rotated on schedule, and finally deleted. A key that has no name, no owner and no known purpose is a liability, because nobody dares delete it and nobody notices if it leaks.

Money questions always land at the Organisation, because that is the only place that sees the whole account.

One subscription, many Projects

An Organisation has one subscription plan. Whatever your plan allows, such as how many members, how many Projects and how many requests, is counted across the whole Organisation. A team that creates a tenth Project does not get a tenth invoice. Its usage simply adds to the total.

What gets counted

Usage in Flagsmith is mostly measured in API requests, which are the questions your applications ask when they want to know the current state of a flag. Every time a mobile app opens, or a server refreshes its flags, requests are counted. The Organisation settings page shows this usage over time, so a finance person or engineering manager can see whether the account is growing faster than planned.

Hosted or self-managed

Because Flagsmith is open source, some companies run it on their own infrastructure, often using containers on a cloud platform. In that setup the Organisation concept still exists and still organises people and Projects, but the billing story is different, since the company is paying for its own servers rather than a hosted subscription. Companies in regulated industries often pick this route to keep all data inside their own network.

Cost control habits

Teams that keep requests under control usually do three things. They cache flag values inside their applications rather than asking on every single page view. They use the server-side pattern of downloading a snapshot and evaluating locally where it suits them. And they review usage monthly, because a bug that polls too often can silently multiply a bill.

A cost thinking exercise

The numbers below are invented purely to teach the idea, so please do not treat them as real prices or limits. Imagine a mobile app with two million active users. Each user opens the app three times a day, and each time the app asks Flagsmith for flags once. That is six million requests a day, or about one hundred and eighty million in a thirty day month. Now imagine a developer changes the app so it also refreshes flags every time the user scrolls a screen. If the average user scrolls forty times a session, the requests could rise by an enormous factor overnight. The cost lesson is not about any one price. It is that a small behaviour change in a client application, multiplied by millions of users, quickly dominates the bill.

The Organisation is where this surprise appears first, because it is the only level that sees combined usage. That is why finance and engineering should share one view of the usage page, and why a regular look at the trend is part of good housekeeping. Large internet companies such as Google and Netflix are well known for treating the cost of every network call as something to design for rather than something to discover on an invoice.

A powerful way to think about Flagsmith is to split it into two halves: the place where people make decisions and the place where applications ask questions.

Two planes

Architects like to divide a system into a control plane and a data plane. The control plane is where configuration is managed by humans: creating Projects, changing permissions, flipping flags. The data plane is where the high speed work happens: millions of applications asking “what is the value of this flag for this user right now?”. In Flagsmith, the Organisation belongs firmly to the control plane. It manages people and rules. The data plane is reached through an Environment and its keys.

flowchart LR
  subgraph CP["Control plane"]
    ADM["Admin dashboard"] --> API["Management API"]
    API --> DB[("Primary database")]
    API --> ORGX["Organisation: members, groups, roles, billing"]
  end
  subgraph DPL["Data plane"]
    LB["Load balancer"] --> FE["Flag evaluation service"]
    FE --> CACHE[("Cache")]
  end
  DB --> FE
  APP["Your web or mobile app with SDK"] --> LB
  SRV["Your backend with SDK"] --> LB
    

Why this split is clever

If the dashboard is slow or temporarily unavailable, your applications should still get their flags. By keeping management and delivery apart, a heavy day of admin work, such as importing hundreds of flags, does not slow down the customers using your website. The Organisation, which is all about people and policy, is rarely in the busy path at all.

What the SDK actually does

An SDK (software development kit) is a ready made library you add to your application so it can talk to Flagsmith without you writing the network code. When your application starts, the SDK uses an Environment key to ask for flags. Many SDKs can then keep a copy in memory and refresh it at intervals, so most decisions are made locally within microseconds. Some server SDKs offer a local evaluation mode in which the whole rule set is downloaded once and decisions never leave your own server. This greatly reduces the number of requests, the delay and the dependency on the network.

Production-scale companies care deeply about this behaviour. Netflix, for instance, has spoken publicly about designing for failure, where a dependency being slow must never break the viewer’s experience. The same thinking applies to flags: a sensible default value in code ensures that if Flagsmith cannot be reached, your application still behaves safely.

Following one flag lookup from start to finish

To make the two planes concrete, follow a single question. A shopper opens a retail app. The app wants to know whether to show the new checkout page.

Notice what was missing from that story: nobody logged in, no member was involved and no permission was checked at that moment. The Organisation did its work earlier, when it decided who was allowed to set up that flag and its rules. At lookup time, only the Environment matters. That is a deliberate and valuable design, because it keeps the part of the system that must be fast away from the part that must be careful.

An Organisation is not static. It is born, it grows, it is reorganised and, sometimes, it is retired. Following that life helps you plan ahead.

The journey of a single permission change

Suppose a new engineer, Aiko, joins the Payments team. A manager adds her to the “Payments Team” group. From that moment, every permission attached to that group applies to her. She can now see the Payments Project and edit flags in Development. Nothing was changed on the Project itself, and nothing needs to be undone when she leaves, other than removing her from the group. This is the whole point of designing with groups: the data flows from the group to the person, never person by person.

No design is perfect. Knowing where the Organisation model shines and where it bites helps you make honest decisions.

The central trade-off: one Organisation or many

The biggest design choice is whether to put everything in a single Organisation or to create several. A single Organisation gives unified governance and a single bill, but every administrator can see everything. Several Organisations give hard walls between business units or customers, at the cost of repeated setup and no central view. There is no universally correct answer. The next chapter shows how experienced architects decide.

Building your own versus using a managed platform

Many teams begin with a homemade solution: a configuration file, a database table or an environment setting. For a handful of switches this is perfectly reasonable. The trouble arrives with growth. Someone must build a dashboard, someone must add permissions, someone must add an audit trail, someone must make delivery fast and resilient and someone must keep all of it secure. Each of these is a small project, and together they become a product that does not earn money for the company. The Organisation model, with its members, groups, roles, keys and audit history, is exactly the set of features that homemade systems tend to lack and later regret.

The honest counter-argument is that a platform adds another dependency and another place to manage. Teams with very few flags, a single developer and no audit needs may be better served by something simple. The right choice depends on size, risk and how many people will touch the switches. If you expect more than a few dozen flags or more than a few people, the structure of an Organisation usually repays its cost.

These are proven shapes that teams use again and again. Pick the one that matches how your company actually works.

How to choose

Ask three questions. First, do people need to see each other’s work? If yes, keep one Organisation. Second, must the billing be separated? If yes, consider separate Organisations. Third, could a mistake in one group damage another? If yes, build a stronger wall, either with tight Project permissions or with separate Organisations.

These traps appear in almost every company that adopts a flag platform. Learn them now and avoid paying for them later.

More small mistakes worth naming

• Putting a server-side or Organisation key inside a mobile app or web page, where anyone can read it.
• Granting permissions to individuals instead of groups, so no one can audit who can do what.
• Forgetting safe default values in code, so a flag outage becomes a product outage.
• Letting Production permissions drift wider over time, because “just this once” was never undone.
• Creating Projects with vague names, so six months later nobody knows which one is real.

Setting rules is half the job. The other half is being able to see afterwards what really happened.

The audit log

An audit log is a diary kept by the system. Every time something important changes, such as a flag being switched on, a segment being edited or a permission being granted, a line is written saying who did it, what changed and when. When a customer complains that a feature vanished at three in the afternoon, the audit log turns a guessing game into a thirty second lookup. How long history is kept, and how much detail is shown, depends on your plan, so check what your account provides.

Webhooks and integrations

A webhook is a small automatic message that Flagsmith sends to another system whenever something happens. A team might connect it to a chat tool so that every Production flag change appears in a shared channel. Flagsmith also offers ready made integrations with analytics and monitoring tools, for example Datadog and Slack, so that a sudden spike in errors can be lined up against the exact moment a flag was changed. This pairing is extremely powerful, because most production incidents are caused by a change, and flags are changes.

Approval flows for risky changes

Higher plans offer change requests, which add a second pair of eyes. One person proposes a change to a Production flag, and another person with the right permission must approve before it takes effect. Some plans also support scheduling a change for a specific time, so a launch can happen at nine sharp without anyone being online at dawn. These features turn the Organisation’s permission layers into a real safety net rather than just a list.

What to monitor at Organisation level

• Usage trend. Is request volume growing as expected, or did a bug just multiply it?
• Member list. Does everyone on the list still work here, and do they still need access?
• Key inventory. Which Organisation and server-side keys exist, who owns them and when were they last rotated?
• Permission drift. Has Production access widened since the last review?
• Stale flags. Which flags have been fully on or fully off for months and should now be removed from the code?

Reading the audit log like a detective

When something odd happens, the audit log is the first place to look, and a few simple questions solve most puzzles. What changed? Find the entry nearest to the moment the problem started. Who changed it? This is rarely about blame. It is about asking the person what they intended, because they often hold the missing context. What was the old value? This tells you exactly how to undo the change. Did anything else change nearby? Many incidents are caused by two small changes made close together, each harmless alone.

Teams that practise this skill build a habit of leaving a short note whenever they change something important, and the habit pays off. A note such as “reduced search results to protect the database during the sale” saves long debates later. It also gives new engineers a quiet education in how the system behaves under stress.

What changes when the company grows from ten engineers to a thousand, and from thousands of requests to millions per minute?

Scaling the people side

The Organisation scales through structure, not through effort. At ten people, one administrator can handle everything by hand. At a thousand, nothing works unless the structure does the work: groups per team, roles per job type, single sign-on for identity, and automation for repetitive tasks. A common growth step is to hand day to day Project administration to the owning team, while a small platform group keeps ownership of Organisation settings.

Scaling the traffic side

Volume is handled in the data plane. Applications that serve millions of users should not ask Flagsmith a fresh question for each page view. Instead they use the caching and local evaluation behaviours of the SDKs, so only a small trickle of requests ever leaves their own network. Some deployments also place a lightweight proxy close to their applications, which answers most questions from a local copy and forwards only updates. The result is both faster responses and a lower usage bill.

flowchart LR
  U["Millions of users"] --> APPS["Your application servers"]
  APPS --> SDK["SDK with local cache"]
  SDK -- "periodic refresh" --> PROXY["Optional local proxy"]
  PROXY -- "occasional sync" --> FS["Flagsmith platform"]
  FS --> ORG["Organisation controls access and billing"]
    

Resilience

High availability means the system stays usable even when parts fail. Flagsmith’s design helps in three ways. Delivery of flags is separate from the admin dashboard, so a dashboard outage does not stop flag evaluation. SDKs can keep serving the last known values if the network is down. And your own code can define defaults, so the worst case is a safe, familiar experience rather than an error page. Together these make the flag layer something you can depend on rather than something you must worry about.

A small capacity thought experiment

Suppose an application serves one hundred thousand requests per second at its busiest moment. If every user request caused a fresh flag lookup, the flag platform would need to answer one hundred thousand questions per second, which is wasteful. With caching inside each application server, perhaps only one lookup per server every thirty seconds is needed. If there are two hundred servers, that is about seven requests per second, a reduction of over ten thousand times. The user still receives a decision in microseconds, because the decision is made from memory.

This is why architects who build for large scale talk about moving decisions closer to where they are used. The same idea appears in content delivery networks, in database read replicas and in the local caches of large retailers. For Flagsmith users, the practical takeaway is to choose your SDK mode deliberately: a client which asks often is simple but costly, a server which caches or evaluates locally is a little more setup but dramatically cheaper and faster at scale.

Here is a practical sequence an architect might follow on day one for a company of about a hundred engineers.

Security work starts by asking a plain question: what could go wrong, who could cause it, and how bad would it be? Architects call this exercise threat modelling.

What is a threat model?

A threat model is a structured list of the valuable things you are protecting, the people or events that could harm them, and the defences you have placed in between. It sounds formal, but you already do it at home. You know your front door is valuable to protect, you know a burglar is a threat, and you know a lock, a light and a neighbour are defences. Doing the same exercise for your Flagsmith Organisation takes about an hour and prevents most nasty surprises.

What are we protecting?

There are four main assets. The first is the live flag values in Production, because they decide what every customer sees. The second is the set of secret keys, because a key is a ready made way in. The third is the member list and permissions, because whoever controls them controls everything else. The fourth is the account itself, including its billing, because an attacker who owns the account can lock out the real owners.

Who might cause harm?

• An outside attacker who steals a password or a key and tries to use it.
• A careless insider who means well but clicks the wrong switch or pastes a secret in the wrong place.
• A malicious insider, rare but real, such as an unhappy employee about to leave.
• A compromised contractor account, where the contractor is honest but their laptop or email was hacked.
• An automated scanner that crawls public code sites around the clock hunting for leaked secrets.

Three kinds of defence

Defences fall into three families. Preventive controls stop bad things from happening, such as two-step verification and narrow permissions. Detective controls notice when something already went wrong, such as audit logs and alerts to a chat channel. Responsive controls limit the damage afterwards, such as a written key rotation plan and a way to switch a flag back within seconds. A mature Organisation has all three. An immature one has only the first, and hopes.

Things will go wrong. What separates calm teams from panicked ones is that the calm teams already wrote down what to do.

A cautionary tale about forgotten flags

One of the most famous software disasters in finance involved a trading firm, Knight Capital, in 2012. In widely reported accounts, a new release reused an old switch that, on one server which had not been updated, woke up long dead code. In roughly forty-five minutes the firm lost something in the region of four hundred million dollars. The exact technical details have been debated, but the lessons are plain and relevant to every Flagsmith user: old flags must be removed, reusing the meaning of a flag is dangerous, and a deployment is only as safe as its least updated server.

Scenario one: the only administrator leaves

If one person is the only administrator and their account is removed, nobody can manage members, keys or billing. Prevent this by always naming at least two administrators from different teams. If it has already happened, the usual recovery path is to contact Flagsmith support with proof of ownership of the company, which is far slower than simply having a spare administrator.

Scenario two: a secret key is leaked

Scenario three: a wrong flag was flipped in Production

The first move is always to put the flag back to its previous value. The audit log shows what the previous value was. Only after customers are safe do you investigate how the change was made. Teams that rehearse this, and that make the previous value easy to find, typically recover in a minute or two.

Scenario four: single sign-on is unavailable

If your company identity system has an outage and Flagsmith relies on it, nobody can log in at exactly the moment you may need to turn something off. Mature teams keep a small number of emergency accounts that are protected by strong passwords and two-step verification, stored in a secure vault, and used only for such events. Every use of an emergency account should be reviewed afterwards. Confirm with your plan and the current documentation how sign-in fallbacks work for your setup.

Scenario five: usage limits are reached

If your applications ask for flags far more often than expected, the Organisation can approach or exceed the request allowance of its plan. What happens next depends on the plan and the current policy, so it is important to know it in advance rather than discovering it in an incident. Set up usage monitoring and an alert at a comfortable margin below the limit, and fix runaway polling in the application that causes it.

Scenario six: Flagsmith itself is unreachable

Design applications so that the worst case is boring. Use defaults in code. Let SDKs keep the last known values. Avoid putting flag lookups on the critical path of a request without a timeout. If a flag controls something truly essential, such as the ability to log in, think carefully about what the default should be and test that path on purpose.

Tools do not run themselves. Governance is the light but clear set of habits and responsibilities that keeps a shared tool useful as more people depend on it.

What is governance?

Governance means deciding who is responsible for what, how decisions are made, and how the group checks that rules are followed. Done badly, governance is a pile of slow approvals that everyone resents. Done well, it is a short page of agreements that nobody has to think about because they are built into the tool.

Who is responsible for what?

A useful way to write this down is a RACI table. RACI stands for Responsible (does the work), Accountable (owns the result and has the final say), Consulted (gives input before) and Informed (told afterwards). Here is a sample for a mid-sized company.

Two lanes of change

Not every change deserves the same care. A sensible model has two lanes. The standard lane covers routine changes, such as turning a flag on for ten percent of users, and needs only the normal permission. The emergency lane covers urgent actions, such as switching off a failing feature, and is intentionally fast. What matters is that the emergency lane still leaves a trail. Anyone using it posts a note in the incident channel, and the change is reviewed the next working day.

A short policy page

The best policy documents fit on one page. They name the administrators, list the groups and what each may do per Environment, state the key rotation schedule, set the quarterly review date and explain how to request access. A page like this gets read. A fifty page policy is signed once and forgotten.

The quarterly review checklist

• Export or read the member list and remove anyone who has left or changed role.
• List all Organisation and server-side keys, confirm an owner for each and rotate any that are old.
• Check who can change Production and compare it to the policy page.
• Look at usage trends and the plan limits for the coming quarter.
• List flags that have not changed in ninety days and decide which to remove.
• Read a sample of audit log entries to confirm they match expectations.

Most companies need exactly one Organisation. A few have good reasons to use more. Here is how to tell the difference.

Do not confuse your customers with your Organisation

A common beginner error is to create a separate Organisation for every end customer of a software product. An Organisation represents the team that manages flags, not the people who use the product. If you run a service with ten thousand business customers and want different behaviour for each, do not create ten thousand Organisations. Instead use identities (the end users or accounts being evaluated) and traits (facts attached to an identity, such as a plan name or a country) together with segments (rules that select groups of identities). One Project and one Environment can serve all ten thousand customers with different results.

When separate Organisations make sense

Merging and acquisitions

When a company buys another, both often arrive with their own Flagsmith Organisation. It is tempting to merge them on day one, but the safer path is staged. First, bring both administrator teams together and agree on the policy page. Then decide which Organisation becomes the long term home. Check the current documentation on what can be moved or exported, since moving Projects between Organisations may require recreating them. Finally, migrate one Project at a time, starting with the least critical.

Self-hosted deployments across regions

Global companies sometimes face laws that require certain data to stay inside a country. In such cases a self-hosted Flagsmith deployed in each region is a common answer, with each deployment having its own Organisation. The trade-off is operational: more systems to patch, back up and monitor, and no single dashboard that shows everything. Many companies accept this cost for regulatory peace of mind, as large cloud customers such as banks and health providers routinely do for their sensitive workloads.

Few teams start from nothing. Most already have switches hidden in configuration files, environment settings and database tables. Adoption is about bringing order to what exists.

The four kinds of flag

Practitioners of the feature flag style often sort flags into four groups, a classification popularised by engineers writing on well known software design sites. Release flags hide unfinished work and are short lived. Experiment flags split users into groups to measure which version performs better and live for weeks. Operational flags let engineers reduce load or disable heavy features during incidents and may live for years. Permission flags give certain customers or staff special access, and can be permanent. Knowing which kind you hold tells you how long it should live and who should be allowed to change it.

A gentle adoption path

Training the people

A tool alone changes little. People need to learn three habits: always release behind a flag, always define a safe default, and always remove the flag when the work is done. A short workshop and a one page cheat sheet beat a long manual. It also helps to appoint a flag champion in each team, someone who answers questions and keeps naming consistent.

Ideas become clear when applied. Let us design access for a fictional company called Northwind Retail.

The company

Northwind has three product teams: Payments, Search and Mobile. It also has a Platform team that runs shared tools, a Security team, a Support team that sometimes needs to check what a customer sees, and an external auditor who visits once a year. There are about eighty people in total. The goals are simple: product teams move fast, Production is protected, and the auditor can see everything without changing anything.

Step one: the structure

One Organisation called Northwind Retail. Three Projects named after the teams, plus one Project for shared platform features. Each Project has Development, Staging and Production Environments with identical names. Two administrators come from the Platform team and one from the Security team.

Step two: the groups

One group per team: Payments Team, Search Team, Mobile Team. One group for the Release Group, which contains a few senior engineers who may change Production. One group for Support, and one for Auditors. Administrators stay out of groups and are named individually, but kept to three people.

Step three: the access grid

This grid is an example of a design, not a copy of actual permission names, which differ between versions. The important pattern is that power narrows as it approaches Production, and that Production changes are concentrated in one small group.

Step four: living with it

Keep this table nearby while you read Flagsmith documentation or talk with your team.

A short list to keep nearby. If you do these ten things, you will avoid most of the pain described earlier.

Quick answers to the questions that come up most often when people first meet the Organisation.