Before comparing the two keys, we need to understand the two jobs a key performs: saying who is asking, and deciding what they may do.

Every request needs an address

Flagsmith serves flags for many customers, many projects, and many environments at the same time. When an SDK sends a request, Flagsmith must instantly know which environment’s flags are wanted. A production environment and a development environment may share a project, and even share feature names, but they hold different values. The key attached to each request is how Flagsmith finds the right one. In this sense, a key works like an address: it points at one specific environment and no other.

Every request also needs permission

An address alone is not enough. If knowing an environment’s address were all it took to read everything inside it, then anyone who learned the address could read everything. So Flagsmith attaches a second meaning to the key: a level of trust. Different keys are allowed to do different things. A key that is meant to be public may only perform a narrow set of low-risk actions. A key that is meant to be secret may perform broader actions, such as downloading the complete rulebook for the environment. The same idea exists in many systems: some identifiers are safe to show, and others are secrets.

Why two keys, not one?

Modern applications run in two very different places. Some code runs on servers you control, where nobody outside your team can look inside. Other code runs on devices you do not control, such as web browsers and phones, where any user can inspect everything. A single key could not serve both safely. If it were secret, front-end code could never use it. If it were public, back-end code would be given too little power or the public would be given too much. Two keys solve this cleanly: a public one with limited abilities, and a secret one with greater abilities.

Three words that are often confused

Security conversations use three similar-sounding words, and keeping them apart makes keys easier to understand. Identification means saying who or what you are, such as giving a name. Authentication means proving it, such as showing a passport that others can check. Authorisation means the system deciding what you may do once it knows who you are. Environment keys touch all three, but not equally.

The client-side ID is mostly about identification: it says “I am asking about this environment”. It proves very little, since anyone can copy it, so it is a weak form of authentication, and that is why its powers are kept small. The server-side key adds real authentication: only someone who holds the secret can present it, so Flagsmith can trust that the caller is one of your own services. That trust is then turned into authorisation: a short list of things such a caller may do, including downloading the rulebook. The design principle is that the more a credential can do, the harder it must be to obtain, and the more carefully it must be kept.

Here is the whole topic in one table. The rest of this guide expands every row.

The easy memory trick

Ask a single question: “could a stranger see this string?” If the code is running in a place a stranger can open, such as a web page, a phone app, or a downloadable program, then the answer is yes, and only the client-side ID belongs there. If the code runs inside a server you control, and the string is loaded from protected storage, the server-side key is both allowed and appropriate. When in doubt, the safer choice is always the one with fewer powers.

Myths and facts

Keys belong to environments, and environments belong to projects. Understanding this hierarchy prevents a whole family of mix-ups.

Flagsmith organises everything in layers. At the top is your organisation, usually your company. Inside it live projects, typically one per product or application. Inside each project live environments, such as development, staging, and production. Inside each environment live your features, with their states, values, segments, and overrides. Keys sit at the environment layer. This is deliberate: it means the environment, and not the project or the organisation, is the unit of access.

What “one environment per key” means in practice

A key for production gives access to production flags only. A key for staging gives access to staging flags only. Even if the two environments contain a feature with the same name, a production key can never read the staging value, and a staging key can never read the production value. This isolation is the reason you can safely let a developer experiment freely in a development environment: the experiment cannot reach production, because the development keys do not point there.

flowchart TD
  Org["Organisation"] --> P1["Project: Shop Web App"]
  Org --> P2["Project: Mobile Backend"]
  P1 --> E1["Environment: Development"]
  P1 --> E2["Environment: Staging"]
  P1 --> E3["Environment: Production"]
  E3 --> K1["Client-side environment ID"]
  E3 --> K2["Server-side key: checkout service"]
  E3 --> K3["Server-side key: reporting job"]
  E1 --> K4["Its own client-side ID and server-side keys"]

Counting keys: how sprawl happens

Key counts grow faster than most teams expect, because they multiply across layers. An organisation with 6 projects, 3 environments each, and 4 server-side keys per environment already has 72 server-side keys, plus 18 client-side IDs. Add temporary environments for pull requests, a handful of experimental sandboxes, and keys for the Edge Proxy, and the total can pass a few hundred within a year. Nobody planned this; it simply accumulates, one reasonable decision at a time.

Sprawl is dangerous because forgotten keys are unmonitored keys. A key that nobody remembers is a key nobody rotates, nobody revokes when a team is disbanded, and nobody would notice being used by a stranger. The remedy is cheap: record every key in an inventory with an owner, review the inventory each quarter, and delete anything without a living owner or a known purpose. Deleting an unused key is a small, safe action, and a short list is far easier to defend than a long one.

It is long, random, and public on purpose. Here is exactly what the client-side ID is, and why exposing it is acceptable.

What it is

The client-side environment ID is a public identifier for one environment. Think of it as the environment’s name tag. When a browser or mobile app starts the Flagsmith SDK, it supplies this ID. Flagsmith reads it and knows which environment’s flags to prepare. The ID is placed into the front-end code, which means that anyone who opens the page’s developer tools, or unpacks the app, can read it. The design assumes this will happen.

What it can do

With only the client-side ID, a caller can ask for the flags that apply to one identity, along with those flags’ on/off state and values. This is what a front end needs: “show me what this particular user should see.” Depending on how the environment is configured, a caller can also send traits for that identity, so that segments can target by them. Those two abilities are all the front end requires.

What it cannot do

Why public is acceptable

Three ideas make exposure tolerable. First, the ID only identifies; it does not unlock management or bulk data. Second, the answers a client can obtain are limited to what a front end legitimately needs: the flags for the identity being asked about. Third, any feature a user can see in the interface will necessarily be visible to that user anyway, because the interface must behave differently. Hiding the flag state from the person whose screen it controls is neither possible nor useful.

How a client SDK uses the ID over time

Following the ID through the life of a client application shows how it behaves in practice. When the application starts, the SDK is given the ID and, usually, an identity for the current user. It sends a request carrying the ID and asks for that identity’s flags. Flagsmith recognises the ID, finds the environment, evaluates the rules for that identity on its side, and returns the results. The SDK stores them in memory, and sometimes on the device, so the interface can read them instantly without waiting for the network again.

During the session, the application may update the identity’s traits, for example after the user changes their plan, and ask again. Each request repeats the same ID. Some client SDKs also support receiving updates when flags change, so the interface can react without a reload; others simply refresh on demand or at intervals. In every case, the ID is a constant companion that tells Flagsmith which environment the questions are about, while the user’s identity, which changes, tells it who they are about.

It looks like the public ID, but it is a different thing altogether: a secret that unlocks more power and demands more care.

What it is

The server-side environment key is a secret credential for one environment. You create it in the dashboard, in the environment’s SDK keys area, and you can create several, each with a name of your choice. The dashboard shows the full value at creation, and you should copy it straight into a secrets manager. Server-side keys typically carry a recognisable prefix, which helps both humans and automated scanners spot them. Check the current documentation for the exact prefix in use.

What it unlocks

Why it is the sensitive one

Remember what the environment document contains: every feature, every segment with its rules, every percentage split, and, where supported, every identity override. With the server-side key, a single request returns all of it. An outsider holding the key could learn which customers are beta testers, how pricing tiers are targeted, which unreleased features are waiting, and how experiments are split. The key does not let them change anything, but knowledge of your targeting logic is itself valuable, and a leaked key is a stubborn problem because it keeps working until someone deletes it.

Many keys, many names

You are not limited to one server-side key per environment, and that is a feature. Create one per service, or one per team, and give each a descriptive name such as “checkout-service-prod”. Separate keys let you trace which service uses which key, revoke a single key without disturbing the others, and rotate keys one service at a time. A single shared key for the whole company is convenient on day one and painful on the day it leaks.

The life of a key from birth to deletion

Every server-side key passes through a lifecycle, and managing it deliberately at each stage is the heart of good key hygiene. It is born when someone creates it in the dashboard, and the full value is shown. It is placed in a secrets manager and linked to the consumer that will use it. It is used every time the service starts, and, in local evaluation, every time the poller refreshes. It is watched by metrics that show authentication failures and by scanners that look for stray copies. It is rotated on a schedule or after an event. Finally it is retired: deleted from Flagsmith and removed from the secrets manager.

The stages most often forgotten are the last two. Teams create and use keys diligently and never retire them. A service is decommissioned, but its key lives on. A contractor leaves, but a key they once copied is still valid. Make retirement a standard step in your decommissioning checklist: when a service is shut down, its keys are deleted the same day. Treat any key without an active consumer as a liability.

A simple map of a typical system shows where each key belongs and where it must never appear.

The diagram below shows a typical product. On the left are the places that users can inspect: a web page in a browser and a mobile app on a phone. These use the public client-side ID. In the middle are your own backend services, running inside your infrastructure. They use server-side keys, loaded from a secrets store at startup. On the right is Flagsmith itself, which reads the key on every request to decide which environment is meant and how much trust to extend.

flowchart LR
  subgraph Untrusted["Places users can inspect"]
    Web["Web browser"]
    Mob["Mobile app"]
  end
  subgraph Trusted["Your protected infrastructure"]
    API["Backend API service"]
    Job["Background worker"]
    SM["Secrets manager"]
  end
  Web -- "client-side ID" --> FS["Flagsmith"]
  Mob -- "client-side ID" --> FS
  SM --> API
  SM --> Job
  API -- "server-side key" --> FS
  Job -- "server-side key" --> FS
  Admin["Engineer using the dashboard"] -- "login and roles" --> FS

The three kinds of caller

Notice that the third caller uses a completely different credential. This separation is important: environment keys are for applications that consume flags, not for people or tools that manage them. If you find yourself wanting to use an environment key to change a flag, you are reaching for the wrong tool, and the answer is an administrative credential with its own permissions.

What actually happens, step by step, when an SDK presents a key? Following one request makes the whole security model concrete.

Every call from an SDK to Flagsmith carries the key in a request header, which is a small label attached to the message, like the address written on an envelope. Flagsmith reads the header first, before looking at anything else. From the key it learns two things at once: which environment the caller means, and which kind of key it is, which decides what the caller is permitted to do.

sequenceDiagram
  participant S as SDK
  participant F as Flagsmith Edge API
  S->>F: Request with the key in a header
  F->>F: Look up the key and find the environment
  F->>F: Decide the key type and its permissions
  alt Key unknown or revoked
    F-->>S: Rejected as unauthorised
  else Key allowed for this action
    F->>F: Evaluate or prepare the response
    F-->>S: Flags or the environment document
  else Key valid but action not allowed
    F-->>S: Rejected as forbidden
  end

Three possible outcomes

Reading the errors

These outcomes show up in your logs as familiar numeric codes, and learning to read them saves hours. An unauthorised result means “I do not recognise you”. Look for typos, trailing spaces, quotes accidentally included, a deleted key, or a key for the wrong installation. A forbidden result means “I recognise you, but you may not do that”. Look for the wrong key type, such as a client-side ID in a place that needs the server-side key. A sudden burst of either, from a service that worked yesterday, points to a recent key change or a deployment that picked up the wrong value.

Protecting the key in transit

A key must travel from your service to Flagsmith, and the journey needs protection. SDK traffic should always use an encrypted connection, known as TLS, which scrambles the contents so that anyone listening on the network sees only noise. The key lives in a request header, and encryption covers headers as well as content. Make sure your SDK is configured with a secure address, beginning with the secure web prefix, and that any internal proxy you pass through is configured not to downgrade the connection.

The less obvious danger is what intermediate systems record. Corporate proxies, load balancers, and observability agents sometimes log request headers for debugging. If they log the header that carries your key, the key is now sitting in a log system with many readers and long retention. Check what your network and monitoring tools capture, and configure them to redact the key header. Do the same for any tool that records outgoing requests from your services, such as tracing or debugging proxies.

The right key depends on one thing: who can read the code that holds it. A short decision path settles it every time.

flowchart TD
  A["Where does the SDK run?"] --> B{"Can a user open or unpack this code?"}
  B -- Yes --> C["Use the client-side environment ID only"]
  B -- No --> D{"Do you need local evaluation or the full rulebook?"}
  D -- Yes --> E["Use a server-side key from a secrets manager"]
  D -- No --> F{"Is the environment variable or file protected?"}
  F -- Yes --> G["Server-side key is allowed, and preferred for backends"]
  F -- No --> H["Fix the storage first, or use the client-side ID"]

Backends that serve front ends

A common design is a front end that needs a few flag decisions, supported by a backend that already knows who the user is. There are two good ways to give the front end its flags. The first is to use a client SDK with the public client-side ID and let it ask Flagsmith directly. The second is to let the backend evaluate the flags with its server-side key and send the needed results to the front end as part of its normal response. The second approach keeps targeting rules, trait handling, and secrets entirely on your side, and is attractive when flag values contain anything you would rather not expose.

Hybrid applications and tricky cases

Real products rarely fit the neat table. A server-rendered web page is built on your server, but then runs in the browser. A desktop application is distributed to customers but talks to your backend. A mobile app may need flags before the user signs in. For each case, apply the same test: where does each line of code actually run, and who can read it there? Server-rendering code can use the server-side key, because it runs privately, but any flag logic that is shipped to the browser afterwards must use the client-side ID, or receive only the results already evaluated on the server.

Edge and serverless platforms deserve a second look. A function running at the edge of a content network is still code you deploy, so it can hold a server-side key, but many such platforms make environment variables visible to every engineer with deployment access. Check who can read those variables, and prefer the platform’s secret storage over plain settings. For desktop software, assume anyone can unpack the program: use only the client-side ID, and send sensitive decisions through your own authenticated backend.

The client-side ID is meant to be public, but “public” is not “harmless”. A careful designer knows exactly what the ID reveals.

Risk one: flag values are visible

Whatever the client SDK can read, a determined person can read, with or without your application. Anyone with the ID can ask what the flags and values are for an identity. This means that remote config values reachable by client SDKs must contain nothing secret. A value that says “show the new banner” is fine. A value that contains an access token, a private URL, or an internal price list is a leak waiting to be found. Keep secrets out of flag values altogether, and keep sensitive configuration in your own secured systems.

Risk two: anyone can invent an identity

The identity label is just text. A curious visitor can ask Flagsmith for the flags of any identity label they like, including labels belonging to real users, if those labels are guessable. If your identity labels are sequential numbers, a visitor can walk through them. Using opaque, unguessable identifiers instead of email addresses or small sequence numbers makes this guessing pointless, and prevents the labels from leaking personal information when they appear in network traffic.

Risk three: segment probing

If a client is allowed to send traits, a curious person can send different traits and watch how the answer changes. By trying “plan equals enterprise”, then “country equals DE”, and so on, they could work out the logic of your segments. This reveals your targeting design rather than breaking anything, but it is a real exposure for businesses that treat pricing tiers or experiments as confidential. Settings exist in the environment to limit what client SDKs may do, and the safest design for sensitive targeting is to evaluate on your server with the secret key, and send only results to the client.

Risk four: noise and abuse

Because the ID is public, someone can send large numbers of requests with it. That can consume your request allowance or create clutter in identity lists. Rate limiting at the platform, plus sensible monitoring on your side, keeps this manageable. For most organisations this is a theoretical annoyance rather than a daily problem, but it is worth knowing about.

Questions to ask before exposing a flag to clients

Before a flag becomes readable by client SDKs, a quick set of questions prevents most exposure problems. Would I be comfortable if this flag’s name and value appeared in a newspaper? Does the name hint at an unreleased product, a customer, or a partnership? Does the value contain anything that could be misused, such as an address, a token, or a threshold that reveals a business rule? Does a segment targeting this flag rely on traits that a visitor could guess and try? If any answer is uncomfortable, move the decision to the server and send only the outcome.

Security people talk about “blast radius”: how much damage one mistake can do. Knowing the radius of a leaked server-side key tells you how urgently to react.

What an attacker gains

Holding a server-side key, an outsider can download the environment document and read the full targeting rulebook for that one environment. They can see segment definitions, identity overrides, percentage splits, flag values, and the names of every feature, including ones not yet released. They can also ask Flagsmith to evaluate flags for any identity, and may be able to send analytics events, which could pollute your usage statistics.

What an attacker does not gain

The key is a consumer credential. It does not let the holder edit features, change segment rules, switch flags on or off, add team members, or touch other environments. This is a vital limit. A leaked key exposes knowledge, but it does not hand over control of your production behaviour. People sometimes panic on the wrong grounds, imagining that an intruder could flip flags and break production. That is not what this key allows; for that, an attacker would need a dashboard login or an administrative token, which are guarded separately.

Indirect consequences worth thinking about

The harm from knowing your rulebook can still be serious. A competitor learning about an unreleased feature, a journalist discovering a pricing experiment, or a malicious user finding the exact conditions under which a safety check is disabled: all are realistic concerns. Rules that mention specific customer identifiers in overrides could also reveal who your beta customers or key accounts are. And where flags guard security-relevant behaviour, such as a weaker check for internal testers, knowing the rule helps an attacker design an attack that fits it.

Estimating the damage in your own organisation

The right level of urgency depends on what your rulebook contains. Walk through a short assessment for the affected environment. How many features does it hold, and are any unreleased or commercially sensitive? Do segment rules encode pricing, eligibility, or fraud checks? Do identity overrides name individual customers or staff? Do any flags weaken a safety or security check for testers? A rulebook full of harmless interface experiments is a small disclosure; one that encodes confidential pricing or security exceptions is a large one, and may justify informing other teams or leadership.

Write the answers down as part of the incident record. They guide the response and also serve as a useful design review. If the assessment shows that sensitive rules sit in an environment read by many services, consider splitting them: keep confidential targeting in a separate project with fewer consumers, so a leak of one key reveals less. Smaller rulebooks with fewer holders are naturally safer, and this is one of the quiet benefits of keeping projects focused.

Flagsmith has more than one kind of secret. Keeping them straight prevents both over-powered applications and under-powered automation.

Environment keys, client-side or server-side, exist so that applications can read flags. A separate family of credentials exists so that people and tools can manage them. These include the dashboard login of each user, protected by whatever sign-in method your organisation uses, and administrative tokens or API keys that scripts and pipelines can present to the management interface. The permissions are different, the storage rules are different, and mixing them up in either direction is a design error.

Two common design errors

Good key hygiene starts at creation. A few minutes of care here saves hours during an incident.

A naming convention that lasts

Choose a consistent pattern and document it. A good pattern contains three pieces of information: the consumer, the environment, and, where you rotate keys, a generation marker. For example, “checkout-api-prod-2026a” tells a future engineer which service uses it, which environment it points at, and that it is the first key of 2026. When you rotate, the new key becomes “checkout-api-prod-2026b”, and the old one is easy to identify and delete.

Who may create and see keys?

Not everyone with dashboard access needs the ability to create or reveal server-side keys. Use the roles and permissions available in your plan to limit this power to a small group, such as platform and security engineers. Developers may need to see the client-side ID, which is public, but have little reason to view production server-side keys. If your process requires a developer to create a key, use a short, documented request flow, so every key has an owner and a record from the start. Keeping creation rights narrow also narrows the number of people who could ever have seen a secret, which makes investigation much simpler after an incident.

A secret is only as safe as the place where it sleeps. Here are the good places, the poor places, and the dangerous ones.

The golden rule of secrets is that they should never be written into anything that travels: source code, container images, build artifacts, documents, chat messages, or screenshots. Instead, they are kept in a dedicated store and delivered to the running service at the last possible moment, in memory, through an identity that the platform controls.

How the key travels to the service

sequenceDiagram
  participant D as Deployment platform
  participant SM as Secrets manager
  participant T as Service task
  participant F as Flagsmith
  D->>T: Start task with its own identity
  T->>SM: Ask for the Flagsmith key using that identity
  SM->>SM: Check the task identity may read this secret
  SM-->>T: Return the key into memory
  T->>F: Start SDK and make requests with the key
  Note over T,SM: The key never appears in code, images or logs

Local development

Developers need keys too, but they do not need production keys. Give each developer, or each shared sandbox, access to a development environment with its own keys. Keep those in a local file that is excluded from version control, or in a developer-friendly secrets tool. Make sure the project’s ignore rules cover such files, and add an automated check that blocks commits containing key-shaped strings. Production keys should be available only to production workloads, never to individual laptops.

Containers, orchestrators and pipelines

Container platforms add special cases. Images are shared widely and cached on many machines, so a key must never be baked into an image; it should arrive when the container starts. Orchestrators such as Kubernetes offer built-in secret objects, but by default these are merely encoded, not strongly protected, so enable encryption at rest, restrict who can read them with access rules, and consider a tool that synchronises values from a real secrets manager into the cluster at runtime. Prefer mounting a secret as a file or injecting it as an environment variable at start, and avoid placing it in a configuration map, which is designed for non-sensitive values and is often more widely readable.

Continuous integration pipelines need keys too, for tests and deployments, and they are a favourite target for attackers, because they run code from many contributors. Store pipeline secrets in the pipeline system’s own secret store, scope each secret to the jobs and branches that truly need it, and never expose secrets to builds triggered from untrusted forks. Use test-environment keys in test jobs, and keep production keys available only to the deployment job that actually needs them. Turn on masking so that accidental printing of a secret appears as asterisks in logs.

Many leaks happen not through carelessness, but through a build tool doing something helpful that nobody noticed.

Modern front-end frameworks make it easy to use environment variables in your code. To prevent accidental exposure, most of them follow a convention: only variables with a special prefix are copied into the browser bundle, and everything else stays on the server. Conventions of this kind include prefixes such as REACT_APP_, NEXT_PUBLIC_, and VITE_. The prefix means “this value is allowed to be public”. The danger is easy to see: if a developer names the server-side Flagsmith key with a public prefix, the build tool dutifully places it in the downloadable bundle, and the secret ships to every visitor.

A safe way to name things

Adopt a naming scheme that makes the type of key obvious from its variable name. For example, name the public one with the word “public” or “client” in it, and the secret one with the word “secret” or “server”. A reviewer reading a change can then spot an error at a glance: a variable with “secret” in its name and a public prefix is a red flag. Combine this with automated checks that scan the built front-end bundle for the secret key’s prefix before every release.

Rotation means replacing a key on purpose, before anyone forces you to. Done well, nobody notices; done badly, production goes dark.

Rotation sounds frightening because the obvious way to do it is dangerous: delete the old key and hope the new one is deployed in time. Flagsmith’s support for several server-side keys per environment makes a much safer way possible. You create the new key first, while the old one still works. You deploy the new key to every consumer. Only when every consumer has switched do you delete the old one. At every moment, every service has at least one working key.

sequenceDiagram
  participant Ops as Engineer
  participant FS as Flagsmith Dashboard
  participant SM as Secrets manager
  participant Svc as Service instances
  Ops->>FS: Create a new key for the same environment
  Ops->>SM: Store the new key as the next version
  Ops->>Svc: Roll out so instances load the new key
  Svc->>FS: Requests now use the new key
  Ops->>FS: Confirm the old key is no longer used
  Ops->>FS: Delete the old key
  Ops->>SM: Remove the old secret version

The rotation steps in plain words

How often?

There is no single right schedule. A common starting point is once or twice a year for routine rotation, and immediately after any suspected exposure, any departure of someone with access to production secrets, or any change of tooling that touched the storage. What matters more than frequency is practice. A team that has rotated a key calmly three times will do it well in an emergency. A team that has never done it will discover its hidden dependencies, such as a forgotten script with the old key pasted in, at the worst possible moment.

How rotations go wrong

Most rotation failures come from a small set of causes, all avoidable. The first is the forgotten consumer: a script, a cron job, or a staging service still using the old key, which breaks the moment it is deleted. Avoid this by naming keys per consumer, so the old key’s name tells you exactly whom to check, and by watching authentication failures after each step. The second is the stale process: a long-running service that read the old key at startup and never restarted, so it keeps using a key you are about to delete. Avoid it by restarting every consumer and confirming from deployment records that none was missed.

The third is deleting too early: removing the old key the moment the new one is created. The fourth is caching in unexpected places: a secrets cache, a sidecar, or a configuration service that keeps handing out the old value for a while. Each of these is easy to fix once you know it exists. The surest way to find them is a rehearsal in a safe environment, where a failure costs a little time and nothing else.

Nobody plans to leak a key, but everybody should plan for it. A short, rehearsed runbook turns panic into procedure.

flowchart TD
  A["Suspected or confirmed exposure"] --> B{"Which key type?"}
  B -- "Client-side ID" --> C["Low urgency: review exposed values and settings"]
  B -- "Server-side key" --> D["Create a replacement key now"]
  D --> E["Deploy the replacement to all consumers"]
  E --> F["Delete the exposed key"]
  F --> G["Review the audit log and access records"]
  G --> H["Assess what the rulebook revealed"]
  H --> I["Fix the cause and write the lessons down"]
  C --> I

The first hour

The next days

After the urgent steps, ask what the rulebook revealed. Were there overrides naming specific customers? Were there unreleased features whose names are sensitive? If so, decide who needs to be told: product owners, account teams, or, in regulated sectors, compliance staff. Then find the root cause. Was the key pasted into a public repository? Did a build tool bundle it into a front end? Was a log level set too high? Fix that cause, add an automated check so the same mistake is caught earlier next time, and record the incident briefly in a shared place, without including the key.

The best incident is the one you catch within minutes. A handful of automated checks do most of the catching.

Catch secrets before they leave

Secret scanning tools look for strings that match known key shapes. They can run on a developer’s laptop before a commit, in your continuous integration pipeline before a merge, and across the history of existing repositories. Many code hosting platforms also offer built-in scanning that alerts you when a recognised secret appears. A recognisable prefix on server-side keys helps these tools find them reliably. Turn the scanning on, route its alerts to a person who will act, and treat each alert as real until proven otherwise.

Watch the signals that point to key trouble

Logs that help and logs that hurt

Your own services should log that authentication failed, which key name or consumer was involved, and when. They must never log the key itself, nor print configuration objects that contain it. A surprising number of leaks come from debug output that dumps all settings during a failure, exactly when engineers are most likely to paste logs into a ticket for help. Mask secrets in configuration printouts, and configure your logging tools to redact values that match your key shape.

A sample key inventory

An inventory need not be fancy. A simple table in a shared, access-controlled document is enough, as long as it is kept current and never contains the key values. The columns that matter are the key’s name, the environment, the consumer, the owner, the storage location, the creation date, and the date of the last rotation.

Reviewing this table each quarter takes minutes and answers the questions that matter in an emergency: who owns each key, where it lives, and how old it is. It also makes it obvious when a key has no owner, which is the signal to investigate and probably delete.

Separate environments are only separate if their keys stay separate. The discipline is simple, and it pays back every day.

flowchart LR
  subgraph Dev["Development environment"]
    DK["Dev keys"] --> DS["Developer sandboxes and local runs"]
  end
  subgraph Stg["Staging environment"]
    SK["Staging keys"] --> SS["Staging services and automated tests"]
  end
  subgraph Prod["Production environment"]
    PK["Production keys"] --> PS["Production services only"]
  end
  Dev -. no key crosses over .- Stg
  Stg -. no key crosses over .- Prod

Rules that keep environments apart

Short-lived environments

Teams that create a temporary environment for each feature branch or pull request face a special case. Each temporary environment gets its own keys, and those keys should be created automatically, given a short life, and deleted when the environment is torn down. Orphaned keys from forgotten environments are a quiet source of risk, because nobody remembers they exist. Include key cleanup in the same automation that removes the environment, and review the key list regularly for unfamiliar names.

A worked example: onboarding a new service

To see these rules in motion, imagine a team launching a new “notifications” service. In the first week, they create three server-side keys: “notifications-dev-2026a” in the development environment, “notifications-stg-2026a” in staging, and “notifications-prod-2026a” in production. Each is stored in the secrets manager of the matching account, readable only by that service’s role. The developers’ laptops use the development key through a local, ignored configuration file. The test pipeline uses the staging key, injected by the pipeline’s secret store, and masked in logs.

At launch, the production key is read only by the production containers. At startup, the service logs the name of the environment its key points to, and the platform team confirms it says production. Three months later, the team records the first rotation in the inventory. A year later, when the service is retired, all three keys are deleted on the same day as the containers. At no point did anyone email a key, paste it into a document, or share one key between environments, and the process cost only a few extra minutes at each stage.

Bigger and more controlled deployments add new places where keys appear. Each needs the same care.

Self-hosted Flagsmith

If you run Flagsmith yourself, environment keys work exactly as described, but the service they point at is yours. The SDKs are given your own API address in addition to the key. Because you also control the database and the servers, you are responsible for protecting the stored keys, for backing up the data that contains them, and for securing the connection between the SDKs and your installation. Use encrypted connections between clients and the server, restrict network access to the management interface, and handle backups of the database as sensitive material, since a backup contains the same secrets as the live system.

The Edge Proxy

An Edge Proxy is a lightweight service placed inside your network to cache environment data and answer SDK requests close to your applications. To do its work, the proxy itself must be configured with the keys of the environments it serves, typically a server-side key, which it uses to fetch environment data, and the matching client-side ID, which it uses to recognise client requests. The proxy therefore becomes a new holder of secrets, and must be treated as one. Store its configuration in your secrets manager, restrict who can read it, and rotate its keys together with the rest.

Multiple regions and clusters

When the same service runs in several regions, you can use one server-side key for all of them, or one per region. Separate keys per region make it easy to see where traffic comes from and to revoke one region without touching the others, at the cost of more keys to manage. Whichever you choose, rotate in a rolling order, region by region, and make sure each region’s secrets store is updated before its services restart.

A few shapes of use keep you safe. A few other shapes appear again and again in incident reports.

Patterns worth adopting

Anti-patterns to avoid

A pattern for sensitive targeting: split the project

One powerful design is to separate flags by sensitivity. Put everyday interface experiments in one project, readable by many services and by client SDKs. Put confidential targeting, such as pricing logic or eligibility rules, in a second project, readable only by one or two trusted backend services, and never by clients. Each project has its own environments and keys, so the keys for the sensitive project exist in far fewer places. If a key for the everyday project leaks, little of value is revealed; if a key for the sensitive project is ever at risk, the list of places to check is short and well known.

A checklist you can run through each quarter, plus a few tests that prove your key handling actually works.

Tests that prove it works

A quarterly review agenda

Set aside thirty to sixty minutes each quarter, with security and platform engineers in the room, and walk through the same short agenda every time. Repetition is the point: a familiar agenda is quick, and gaps stand out.

The split between a public identifier and a secret key is not unique to Flagsmith. It is one of the most common ideas in modern software, and the failures follow familiar patterns too.

An illustrative setup on AWS

To bring everything together, here is one typical arrangement for a product running on Amazon Web Services. It is an example of how the pieces fit, not a required recipe. The single-page front end is served from a content delivery network and carries only the public client-side ID. The backend runs as containers on Amazon ECS. Each service has its own server-side key, stored as a secret in AWS Secrets Manager, and each task role may read only its own secret. Metrics for authentication failures, labelled by key name, flow to Amazon CloudWatch, with alarms. A scheduled rotation job creates a new key in Flagsmith, stores it as a new secret version, triggers a rolling restart, and deletes the old key after verification.

flowchart LR
  U["Users"] --> CDN["Content delivery network with the front end"]
  CDN -- "client-side ID only" --> FS["Flagsmith"]
  U --> ALB["Application Load Balancer"]
  ALB --> T1["ECS task: checkout service"]
  ALB --> T2["ECS task: catalogue service"]
  SM["AWS Secrets Manager"] --> T1
  SM --> T2
  T1 -- "its own server-side key" --> FS
  T2 -- "its own server-side key" --> FS
  T1 --> CW["CloudWatch metrics and alarms"]
  T2 --> CW
  Rot["Rotation job"] --> SM
  Rot --> FS

What the incidents have in common

Looking across the examples above, a few patterns repeat. The secret was in the wrong place: a repository, a public bundle, a log. Nobody noticed for a long time, because a leaked key does not announce itself. The damage came from reach: the key could do more than its holder needed. And the fix, once discovered, was always the same: replace the key and find the cause.

Each pattern has a matching defence in this guide. For the wrong place, use a secrets manager and scan builds. For the long silence, use scanners, alerts, and a quarterly review. For excessive reach, create narrow keys per consumer in one environment, and remember that Flagsmith’s own design limits what a server-side key can do. None of these defences is exotic; they are routine habits, and the incidents are reminders of what happens when the habits are skipped.

Short answers to the questions that come up most often about environment keys.

The whole story in one place: what to remember when you close this page and open your configuration.

Every Flagsmith environment offers two keys because applications run in two kinds of places. The client-side ID is a public address that lets browsers and apps ask what one identity should see. The server-side key is a secret credential that lets trusted backends read flags and download the whole environment document. Keeping the first public and the second private, storing secrets properly, rotating with overlap, and watching for trouble are the habits that keep feature flags a convenience and not a liability.