Reference
Kill switch
On this page
What it does
Using the kill switch publishes a new, signed revision of the environment, marked as an emergency revision (kind: "kill"). It contains exactly what was already published, with one difference: the flag you chose is turned off, so every SDK serves its published off value. It is distributed like every other revision, so connected SDKs usually apply it within a second (in our production check, a median of 178 ms from commit to the SDK's update event).
- Skipped for this one revision: the requirement to publish through a change, approvals, and scenario checks.
- Not skipped: your role, two-step verification where your organization requires it, a typed reason, the rate limit, and the audit log.
- Nothing else changes: other flags and segments stay as published, and pending draft work is not published.
- Environments where the flag is not published, already off or already killed are skipped and reported.
Who can use it
By default, owners and admins. An owner can change this under Settings → Organization → Kill switch to owners only, or to owners, admins and editors. Viewers can never use it. If the organization requires two-step verification, everyone who uses the kill switch must have verified with an authenticator in the current session, editors included, because it bypasses review.
From the dashboard
Open the flag and choose Kill switch. The dialog shows the environments (the one selected in the sidebar, or every environment where the flag is on), what users get now and after the kill (the off value per environment), and asks for a reason. After confirming, the flag page and the flags list show the flag as Killed in that environment, with who killed it, when, and why.
What happens to your draft
The draft is kept and rebased on the kill: the flag is also turned off in the draft of each killed environment, and every other pending edit (including the flag's own rules and values) stays. A later normal publish therefore cannot silently turn the flag back on. Two consequences to expect:
- Approvals given to the previous draft become stale, because the reviewed content changed. Approve again after the incident.
- A pending scheduled publish of that environment fails safely (the draft and the destination revision it pinned have changed); schedule it again.
Turning it back on
Choose Restore on the flag page (editor role). This turns the flag on in the environment's draft and opens a change for it. Publish that change as usual: it needs the approvals and scenario checks the environment requires. The flag stops being shown as killed once a revision serves it enabled again, whoever publishes it.
Management API
Both calls need an API token with the flags:kill scope. The scope is never implied by flags:write or publish. Send an Idempotency-Key so a retried request cannot kill twice. See the Management API reference for every field and error.
curl -X POST https://edge.nanoflags.io/api/v1/projects/commerce/flags/new-checkout/kill \
-H "Authorization: Bearer $NANOFLAGS_API_TOKEN" \
-H "Idempotency-Key: incident-4711" \
-H "Content-Type: application/json" \
-d '{ "environment": "production", "reason": "Checkout errors spiking since the 14:00 release" }'
# then, after the incident: open the reviewed restore change
curl -X POST https://edge.nanoflags.io/api/v1/projects/commerce/flags/new-checkout/restore \
-H "Authorization: Bearer $NANOFLAGS_API_TOKEN" -H "Content-Type: application/json" \
-d '{ "environment": "production" }'| Status | Code | Meaning |
|---|---|---|
| 403 | FORBIDDEN | The token's creator does not have the organization's kill-switch role. |
| 403 | INSUFFICIENT_SCOPE | The token lacks flags:kill. |
| 409 | ALREADY_KILLED | The flag is already killed in the chosen environment(s). |
| 409 | NO_CHANGES | The flag is not published, or already off, there. |
| 422 | REASON_REQUIRED | The reason is missing or shorter than 8 characters. |
| 429 | RATE_LIMITED | Too many kills (see below). |
CLI
export NANOFLAGS_API_TOKEN=nf_api_… # token with the flags:kill scope
nanoflags flags kill new-checkout --env production --reason "Checkout errors spiking since the 14:00 release"
nanoflags flags restore new-checkout --env productionAdd --project <key> when the token can see several projects, --all-environments instead of --env to kill everywhere, and --json for machine-readable output. See CLI.
Notifications and audit
- Every owner and admin of the organization receives an e-mail right away (it cannot be turned off), with the flag, the environments, the reason and who used it.
- Webhook events
flag.killed(one per environment) andflag.kill_restored, plus the usualpublish.completedfor the new revision. See Webhooks. - The audit log records
flag.killedwith the reason, the new and previous revision and the off value, and the revision appears in the history with its note.
Safeguards
- A person can use the kill switch at most 5 times in 10 minutes, and an organization at most 20 times an hour.
- An organization that is suspended cannot publish, including with the kill switch; the configuration already published keeps being served.