Skip to content
FlagSwiftDocs

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 a version (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 renamed key-projectkey (the report says so in warnings) with that project's flags following it.
  • Importing never deletes. skip leaves what exists alone and adds the rest; overwrite replaces 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. dryRun defaults to true, so applying has to be asked for with false.
  • 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#

GET/api/organization

Includes 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”.
Request
curl -s -b "auth_session=$SESSION" "$FLAGSWIFT_URL/api/organization"
200OK
{
  "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#

PATCH/api/organization

Authorization

organization.update

Body

  • namestringRequired

    2 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”.
Request
curl -s -b "auth_session=$SESSION" -X PATCH "$FLAGSWIFT_URL/api/organization" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Acme Payments" }'
200OK
{ "status": "success", "message": "Organization saved", "data": { "id": "ORGANIZATION_ID", "name": "Acme Payments" } }

Overview numbers#

GET/api/stats/overview

The 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.
Request
curl -s -b "auth_session=$SESSION" "$FLAGSWIFT_URL/api/stats/overview"
200OK
{
  "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#

POST/api/organization/deactivate

Owner 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”.
Request
curl -s -b "auth_session=$SESSION" -X POST "$FLAGSWIFT_URL/api/organization/deactivate"
200OK
{ "status": "success", "message": "Organization deactivated", "data": { "deactivatedAt": "2026-10-03T12:00:00.000Z" } }
What stops and what still works
AreaDescription
Console and Dashboard APIEvery 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 keysRequests with any key are refused, so SDKs fall back to their cache or defaults.
Sign-inOnly the owner can sign in. Others see a message that the organization is deactivated.
SessionsExisting sessions are ended so the change takes effect at once.

Reactivate#

POST/api/organization/reactivate

Owner 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”.
Request
curl -s -b "auth_session=$SESSION" -X POST "$FLAGSWIFT_URL/api/organization/reactivate"
200OK
{ "status": "success", "message": "Organization reactivated", "data": { "deactivatedAt": null } }

SDKs keep serving

Server SDKs keep their last configuration and client SDKs their cache, so users do not notice. They pick up changes again after reactivation.

Export and import configuration#

Export#

GET/api/config/export

Downloads 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

  • projectsstring

    Comma-separated project keys to export, for example web,api. Up to 2,000 characters. Leave it out to export every project.

Errors

  • 400A projects value over 2,000 characters.
  • 401No session, or it has expired (“Authentication required”).
  • 403Your role lacks config.export, or the organization is deactivated.
Request
curl -s -b "auth_session=$SESSION" -D - -o flagswift-config.json \
  "$FLAGSWIFT_URL/api/config/export?projects=web,api"
200OK
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#

POST/api/config/import

The 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.

Report fields
FieldTypeDescription
appliedbooleanTrue only when changes were written. A dry run or a refused file reports false.
summaryobjectFor 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.
warningsstring[]Worth knowing, but they do not stop it.

Authorization

config.import

Body

  • documentobjectRequired

    The 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 | overwrite

    skip (the default) leaves anything that already exists alone; overwrite replaces it with the file's version.
  • dryRunboolean

    Defaults to true: the file is checked and reported on without writing. Send false to apply it.

Errors

  • 400“Choose a configuration file” (no document), a mode other than skip or overwrite, 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.
Request
# 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 @-
200OK
{
  "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#

bash
# 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#

bash
# 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"