Skip to content
FlagSwiftDocs

Put production behind review

Make changes to a sensitive environment go through a proposal and a reviewer, so no single person can change what production users see.

Time
About 8 min
Who can do it
An Admin turns it on (environments.update). Release managers and Admins review.
Where
Environments, then Releases
You finish with
Changes to an environment wait for a second person

What and why#

What it is#

Require approval is a switch on an environment. While it is on, nobody changes what that environment serves directly. They propose a release, and a Release manager or an Admin reads it and approves or rejects it. Only then do the changes run, at the times the proposer chose.

When to use it#

  • Production, where a wrong toggle is seen by customers.
  • Any environment where your organization wants a second pair of eyes or an audit trail of who approved what.

How it works#

What the switch holds back, and what it does not
ActionDescription
Held for approvalSwitching the flag on or off, and changing the rollout percentage, targeting lists, rules, segments, prerequisites, Roll out by or variant allocation in that environment. Direct attempts are refused with APPROVAL_REQUIRED.
Goes through a releaseTurning the flag on or off and moving the percentage, as a scheduled change or a staged rollout.
Never held upThe kill switch and a rollback. In an incident they take effect at once and are recorded in the audit log.
Not coveredEditing a segment, which is shared by every environment, and editing a flag's variants or details.

Developers are reviewed everywhere

Independent of this switch, a release proposed by someone who cannot review releases, such as a Developer, always waits for a Release manager or an Admin, in every environment.

Before you start#

  • The environments.update permission to turn the switch on. Only Admins have it by default.
  • At least two people who can review: Release managers or Admins, since nobody approves their own release by default.
  • Know that approval-required environments take only on/off and percentage changes. Targeting, rules and segments cannot be carried by a release, so plan those changes in an environment without approval, or turn the switch off briefly.

Walk through it#

  1. Turn on Require approval

    Open Environments, choose the edit button next to the environment, usually Production, and switch on Require approval. Choose Save Changes, which stays off until something changed. The setting is per environment, so Development can stay open.

    Fields in the Edit environment dialog
    FieldDescription
    NameThe display name.
    KeyShown for reference. It is used by SDKs and flag history and cannot be changed.
    Production environmentWithdraws toggles, rollouts, targeting and the kill switch from Developers and Product managers. It cannot be switched off for the environment keyed production.
    Require approvalChanges cannot be made directly. Someone proposes a release and a reviewer approves it. The kill switch still works at once.
    The Edit environment dialog with Require approval switched on. Save Changes stays disabled until something changes.
    You should see. The environment list shows an Approval required badge beside its name.
  2. Propose a change

    From now on, direct changes in that environment are refused with Production requires approval. Propose a release instead of changing it directly. The proposer opens the flag, chooses the Releases tab and Propose release, picks the environment and describes the change. The dialog says requires approval. A release manager or admin must approve this before anything changes. The proposer can name a Reviewer, who is told, but any Release manager or Admin can decide. See Schedule a change or a staged rollout.

  3. Review it

    A Release manager or Admin opens Releases, filters by Needs approval, and reads the card: the flag, the environment, the reason and every stage with its time. They choose Approve or Reject.

    A proposal waiting for review, as a release manager sees it. The proposer sees Cancel instead of Approve and Reject.
    The review dialog
    DecisionDescription
    ApproveA note is optional, up to 500 characters. Approving applies the changes at the times shown, with the reviewer's own access. Steps whose time has passed run straight away.
    RejectA reason is required, up to 500 characters. The proposer sees it and it is recorded in the audit log. The stages are cancelled.
    The review dialog. Reject needs a reason, and an empty one shows the message in red under the field.
    You should see. An approved release moves to Scheduled with the reviewer's email and note under Show details. A rejected one reads Rejected with the reason.

    Nobody approves their own change

    The person who proposed a release cannot approve it, unless the deployment sets ALLOW_SELF_APPROVAL=true. The Approve button is hidden on your own release. Only the proposer can cancel a proposal: reviewers reject instead.

    The reviewer needs the right to make the change

    Because the reviewer's authority is what applies each step, approving is refused if the reviewer could not make those changes themselves in that environment. A Release manager or an Admin can in production.
  4. Keep the emergency route open

    The kill switch and a rollback are never held up by approval. When something is on fire, a person with the right role can stop it immediately and the change is recorded in the audit log. See Handle an incident with the kill switch.

Limits today

There is one approver per release; multiple approvers are not available. A request nobody reviews is cancelled after 72 hours with the note Not reviewed within 72 hours, so tell your reviewer when a proposal is waiting.

Do it with the API#

These are Dashboard endpoints and authenticate with your signed-in session cookie (auth_session), not an API key.

Turn the switch on

Needs environments.update. Find the id with GET /api/environments. You can send displayName and isProduction in the same call.

Request
curl -s -X PATCH "https://flags.example.com/api/environments/$ENVIRONMENT_ID" \
  -b "auth_session=$SESSION" \
  -H "Content-Type: application/json" \
  -d '{"requiresApproval": true}'
200 OK
{
  "status": "success",
  "message": "Environment updated successfully",
  "data": {
    "id": "664fa1b2c3d4e5f6a7b8c9d0",
    "name": "production",
    "displayName": "Production",
    "order": 2,
    "isDefault": true,
    "isProduction": true,
    "requiresApproval": true
  }
}

Approve or reject a release

Both need releases.review. See the Releases API for proposing, listing and cancelling.

Request
# Approve (note optional)
curl -s -X POST "https://flags.example.com/api/releases/$RELEASE_ID/approve" \
  -b "auth_session=$SESSION" -H "Content-Type: application/json" \
  -d '{"note":"Checked the stages, fine to go"}'

# Reject (reason required)
curl -s -X POST "https://flags.example.com/api/releases/$RELEASE_ID/reject" \
  -b "auth_session=$SESSION" -H "Content-Type: application/json" \
  -d '{"note":"Hold until after the freeze"}'
200 OK (trimmed)
{
  "status": "success",
  "message": "Release approved",
  "data": {
    "id": "6650e3b4c5d6e7f8a9b0c1d2",
    "status": "scheduled",
    "requiresApproval": true,
    "reviewedByEmail": "release-manager@example.com",
    "reviewNote": "Checked the stages, fine to go",
    "reviewedAt": "2026-10-03T10:41:09.000Z",
    "nextRunAt": "2026-10-05T09:00:00.000Z"
  }
}

What to check#

  • Propose a release as a Developer and confirm it waits for review.
  • Try to approve it as the same person and confirm it is refused (or the button is missing).
  • Try to toggle the flag directly and confirm you get APPROVAL_REQUIRED.
  • Find the proposal, the approval and each applied step in the audit log.

If something goes wrong#

Production requires approval. Propose a release instead of changing it directly. (APPROVAL_REQUIRED)

Why: Require approval is on for the environment and you tried a direct toggle, percentage or targeting change.

Fix: Propose a release. For targeting, rules and segments, which a release cannot carry, make the change in an environment without approval or ask an Admin to switch the setting off while you do it.

Ask someone else to approve your release (SELF_APPROVAL)

Why: You proposed this release and self-approval is off.

Fix: Ask another Release manager or Admin. A server administrator can set ALLOW_SELF_APPROVAL=true if that fits your policy.

This release is no longer waiting for approval (409)

Why: Someone else already approved or rejected it, the proposer cancelled it, or it expired.

Fix: Refresh the Releases page and read its current status.

Approving is refused with a permission error

Why: The reviewer could not make those changes themselves in that environment, for example a custom role without rollouts.update or flags.toggle.

Fix: Ask a Release manager or an Admin to review it.

Give a reason for rejecting this release

Why: Reject needs a note.

Fix: Type why, up to 500 characters, and reject again.

I cannot find the Require approval switch

Why: Only roles with environments.update, by default Admins, see the edit button.

Fix: Ask an Admin.

Good to know#

Why does my own proposal show no Approve button?
The card shows Approve and Reject only to reviewers who did not propose it. On your own release it reads Waiting for someone else to review, and you can Cancel it.
Does approval apply to the kill switch?
No. The kill switch and rollbacks are deliberately exempt, so an emergency is never held up by a review.
Who is told about a request?
Everyone who can review is told. If the proposer named a reviewer, that person is emailed on their own and the card shows who was asked. Anyone who can review can still decide.
Can I require approval for only some flags?
No. The switch belongs to the environment and covers every flag in it.
What happens to releases already scheduled when I turn the switch on?
They keep their status. The switch changes how new proposals start and refuses direct changes.