Organization
The organization's name, its overview numbers, exporting and importing its configuration, and switching it off and on.
Concepts#
What the organization is#
Everything in FlagSwift lives inside one organization: its members, projects, environments, flags, segments, keys and history. Every Dashboard API call acts on the organization of the signed-in session, so there is no organization id in any path. The alias is its stable handle: renaming it never breaks links or keys.
The owner is the administrator who founded it, or who received ownership. Only the owner can deactivate or reactivate it. See Members for how ownership moves.
Export and import semantics#
- The file holds configuration: projects, environments, segments, flags (with each environment's targeting, rollout and rules) and custom roles. It does not hold people, API keys, secrets, history, audit entries, metrics or code references.
- It is identified by
format: "flagswift.config"and aversion(currently 1). Other versions are refused. - Things are matched by key (project, flag, segment) or name (environment, role), not by id, so a file moves cleanly between organizations and instances.
- Segments belong to the organization, so the file lists them once, with no project, and any project's flags may use them. Files exported before this change, where each segment names a
project, are still accepted: the same key with the same content in several projects becomes one segment, and a key that clashes with different content is renamedkey-projectkey(the report says so inwarnings) with that project's flags following it. - Importing never deletes.
skipleaves what exists alone and adds the rest;overwritereplaces what exists with the file's version. - It is all or nothing: one problem anywhere and nothing is written. Applying runs in one transaction.
- Always dry-run first.
dryRundefaults totrue, so applying has to be asked for withfalse. - Limits per file: 8 MB, 200 projects, 50 environments, 5,000 flags, 2,000 segments and 25 roles.
- Where an environment requires approval, flag changes in it are not applied and the report says so in
warnings; new flags there are created switched off. Flags whose kill switch is active are left unchanged. A new environment is added to every existing flag, switched off. - You cannot import roles with more permissions than you hold yourself, and importing is audited as
config.imported.
What deactivation means#
Deactivating switches the organization off without deleting anything. It is reversible, instant for everyone, and meant for pausing access, not for removing data.
Details#
Get the organization#
/api/organizationIncludes whether it is deactivated (deactivatedAt is a time, or null when active). This is one of the two calls that still work while it is deactivated. system shows read-only deployment settings (never secrets) and is null unless your role holds organization.update.
Authorization
organization.read
Errors
- 401No session, or it has expired (“Authentication required”).
- 403Your role lacks
organization.read. - 404“Organization not found”.
curl -s -b "auth_session=$SESSION" "$FLAGSWIFT_URL/api/organization"{
"status": "success",
"message": "Organization fetched",
"data": {
"id": "ORGANIZATION_ID",
"name": "Acme",
"alias": "acme",
"createdAt": "2026-08-01T10:00:00.000Z",
"deactivatedAt": null,
"members": 12,
"projects": 3,
"environments": 3,
"system": {
"database": "postgres",
"metricsEnabled": true,
"metricsRetentionDays": 30,
"schedulerEnabled": true,
"rateLimitEnabled": true,
"evaluationCacheTtlSeconds": 30,
"allowSelfApproval": false,
"prometheusEnabled": true
}
}
}Rename#
/api/organizationAuthorization
organization.update
Body
namestringRequired2 to 100 characters. Trimmed, and runs of spaces collapse to one. Sending the current name changes nothing (no audit entry).
Errors
- 400“Enter the organization name”, “Use at least 2 characters” or “Keep the name under 100 characters”.
- 401No session, or it has expired (“Authentication required”).
- 403Your role lacks
organization.update, the organization is deactivated, or the request was blocked as cross-site. - 404“Organization not found”.
curl -s -b "auth_session=$SESSION" -X PATCH "$FLAGSWIFT_URL/api/organization" \
-H "Content-Type: application/json" \
-d '{ "name": "Acme Payments" }'{ "status": "success", "message": "Organization saved", "data": { "id": "ORGANIZATION_ID", "name": "Acme Payments" } }Overview numbers#
/api/stats/overviewThe numbers behind the dashboard overview: totals, how many flags are on per environment, targeting and kill-switch counts, the stalest flags, and recent flag activity. It takes no parameters. A flag counts as stale after 30 days untouched; stale.items lists at most the 5 stalest and activity the 8 most recent changes, while stale.count is the full number. Archived flags, and flags of archived projects, are left out. For usage over time, see the metrics endpoints.
Authorization
organization.read
Errors
- 401No session, or it has expired (“Authentication required”).
- 403Your role lacks
organization.read.
curl -s -b "auth_session=$SESSION" "$FLAGSWIFT_URL/api/stats/overview"{
"status": "success",
"message": "Stats fetched successfully",
"data": {
"totals": { "flags": 41, "projects": 3, "environments": 3, "projectsWithoutFlags": 0 },
"flagsByProject": { "PROJECT_ID": 30, "PROJECT_ID_2": 11 },
"environments": [
{ "name": "production", "displayName": "Production", "totalFlags": 41, "enabledFlags": 22, "percentEnabled": 54 }
],
"targeting": { "flagsWithTargeting": 6, "targetedUsers": 48, "partialRollouts": 4, "activeKillSwitches": 0 },
"stale": {
"thresholdDays": 30,
"count": 3,
"items": [
{ "id": "FLAG_ID", "name": "old-banner", "displayName": "Old banner", "projectId": "PROJECT_ID", "staleDays": 61 }
]
},
"activity": [
{
"id": "ACTIVITY_ID",
"flagId": "FLAG_ID",
"flagName": "checkout-v2",
"flagDisplayName": "Checkout v2",
"projectId": "PROJECT_ID",
"action": "toggle",
"environment": "production",
"environmentDisplayName": "Production",
"summary": "enabled in Production",
"tone": "enabled",
"userEmail": "rm@example.com",
"createdAt": "2026-10-03T09:12:31.000Z"
}
]
}
}Deactivate and reactivate#
Deactivate#
/api/organization/deactivateOwner only. Nothing is deleted. While deactivated:
Authorization
organization.deactivate
Errors
- 401No session, or it has expired (“Authentication required”).
- 403“Only the owner can deactivate or reactivate the organization”.
- 404“Organization not found”.
- 409“This organization is already deactivated”.
curl -s -b "auth_session=$SESSION" -X POST "$FLAGSWIFT_URL/api/organization/deactivate"{ "status": "success", "message": "Organization deactivated", "data": { "deactivatedAt": "2026-10-03T12:00:00.000Z" } }| Area | Description |
|---|---|
| Console and Dashboard API | Every call is refused with 403 and the message “This organization is deactivated. Its owner can reactivate it.”, except reading the organization and the owner reactivating it. |
| API keys | Requests with any key are refused, so SDKs fall back to their cache or defaults. |
| Sign-in | Only the owner can sign in. Others see a message that the organization is deactivated. |
| Sessions | Existing sessions are ended so the change takes effect at once. |
Reactivate#
/api/organization/reactivateOwner only. Everything returns as it was: flags, keys, members and history. Because sessions were ended, the owner signs in again first.
Authorization
organization.deactivate
Errors
- 401No session, or it has expired (“Authentication required”).
- 403“Only the owner can deactivate or reactivate the organization”.
- 404“Organization not found”.
- 409“This organization is already active”.
curl -s -b "auth_session=$SESSION" -X POST "$FLAGSWIFT_URL/api/organization/reactivate"{ "status": "success", "message": "Organization reactivated", "data": { "deactivatedAt": null } }SDKs keep serving
Export and import configuration#
Export#
/api/config/exportDownloads the organization's projects, environments, segments, flags and custom roles as one JSON file named flagswift-config-YYYY-MM-DD.json. The body is the file itself, not the JSON envelope. projects optionally narrows it to those project keys, comma separated. Each export is audited.
Authorization
config.export
Query parameters
projectsstringComma-separated project keys to export, for example web,api. Up to 2,000 characters. Leave it out to export every project.
Errors
- 400A
projectsvalue over 2,000 characters. - 401No session, or it has expired (“Authentication required”).
- 403Your role lacks
config.export, or the organization is deactivated.
curl -s -b "auth_session=$SESSION" -D - -o flagswift-config.json \
"$FLAGSWIFT_URL/api/config/export?projects=web,api"HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Disposition: attachment; filename="flagswift-config-2026-10-03.json"
Cache-Control: no-store
{
"format": "flagswift.config",
"version": 1,
"exportedAt": "2026-10-03T12:00:00.000Z",
"projects": [ { "key": "web", "name": "Web app", "description": "", "color": null, "archived": false } ],
"environments": [ { "name": "production", "displayName": "Production", "order": 2, "isProduction": true, "requiresApproval": true } ],
"segments": [],
"flags": [
{
"project": "web",
"key": "checkout-v2",
"displayName": "Checkout v2",
"description": "",
"type": "boolean",
"variants": [],
"owner": null,
"expectedRemovalAt": null,
"expiresAt": null,
"permanent": false,
"archived": false,
"environments": { "production": { "enabled": true, "rolloutPercentage": 25, "targeting": { "...": "..." } } }
}
],
"roles": []
}Check or apply a file#
/api/config/importThe reply is always the report: what would be created and updated, every problem found, and warnings. A refused file is a 200 with errors and nothing is changed. Applying runs in one transaction and never deletes. Files over 8 MB are rejected. See Export and import.
| Field | Type | Description |
|---|---|---|
| applied | boolean | True only when changes were written. A dry run or a refused file reports false. |
| summary | object | For each of projects, environments, segments, flags and roles: how many would be created, updated or skipped. |
| errors | { path, message }[] | Problems that stop the import. Nothing is written while any exist. |
| warnings | string[] | Worth knowing, but they do not stop it. |
Authorization
config.import
Body
documentobjectRequiredThe exported file, as is: format, version, exportedAt, projects, environments, segments, flags and roles. At most 8 MB, 200 projects, 50 environments, 5,000 flags, 2,000 segments and 25 roles.modeskip | overwriteskip (the default) leaves anything that already exists alone; overwrite replaces it with the file's version.dryRunbooleanDefaults to true: the file is checked and reported on without writing. Send false to apply it.
Errors
- 400“Choose a configuration file” (no
document), amodeother thanskiporoverwrite, invalid JSON, or “The file is too large. The limit is 8 MB.”. - 401No session, or it has expired (“Authentication required”).
- 403Your role lacks
config.import, the organization is deactivated, or the request was blocked as cross-site. - 409Something in the file was created by someone else while it was importing. Nothing was changed; run it again.
# Check first (dryRun defaults to true). jq wraps the exported file as "document".
jq '{ document: ., mode: "skip" }' flagswift-config.json \
| curl -s -b "auth_session=$SESSION" -X POST "$FLAGSWIFT_URL/api/config/import" \
-H "Content-Type: application/json" --data-binary @-
# Then apply it
jq '{ document: ., mode: "skip", dryRun: false }' flagswift-config.json \
| curl -s -b "auth_session=$SESSION" -X POST "$FLAGSWIFT_URL/api/config/import" \
-H "Content-Type: application/json" --data-binary @-{
"status": "success",
"message": "Checked. Nothing was changed.",
"data": {
"applied": false,
"dryRun": true,
"mode": "skip",
"summary": {
"projects": { "create": 1, "update": 0, "skip": 0 },
"environments": { "create": 0, "update": 0, "skip": 3 },
"segments": { "create": 0, "update": 0, "skip": 0 },
"flags": { "create": 12, "update": 0, "skip": 4 },
"roles": { "create": 1, "update": 0, "skip": 0 }
},
"errors": [],
"warnings": [
"2 flag configurations in \"production\" were not applied because that environment requires approval. New flags there are created switched off."
]
}
}Common patterns#
Copy staging configuration to a new instance#
# 1. Export from the source instance
curl -s -b "auth_session=$SRC_SESSION" -o config.json "$SRC_URL/api/config/export"
# 2. Dry-run on the target; read errors and warnings in the report
jq '{ document: ., mode: "skip" }' config.json \
| curl -s -b "auth_session=$DST_SESSION" -X POST "$DST_URL/api/config/import" \
-H "Content-Type: application/json" --data-binary @- | jq '.data | {errors, warnings, summary}'
# 3. Apply when errors is empty
jq '{ document: ., mode: "skip", dryRun: false }' config.json \
| curl -s -b "auth_session=$DST_SESSION" -X POST "$DST_URL/api/config/import" \
-H "Content-Type: application/json" --data-binary @-Pause the whole organization, then resume#
# As the owner
curl -s -b "auth_session=$OWNER_SESSION" -X POST "$FLAGSWIFT_URL/api/organization/deactivate"
# Sessions were ended: sign in again as the owner, then
curl -s -b "auth_session=$OWNER_SESSION" -X POST "$FLAGSWIFT_URL/api/organization/reactivate"