Skip to content
FlagSwiftDocs

Manage your organization

Rename the organization, read its overview and, if you ever need to, switch it off and back on.

Time
About 8 min
Who can do it
Admins can read and rename it (organization.update). Only the owner can deactivate or reactivate it
Where
Settings, in the console
You finish with
A correct organization name, or an organization switched off and back on

What and why#

Your organization is the container for everything else: projects, environments, flags, members, keys and history. Settings is where you check how big it has grown, change its name and, as the owner, take it offline without deleting anything. Settings also holds the shortcuts to every page that configures the workspace and, for people who can edit the organization, a read-only view of how the server is set up.

Before you start#

  • Reading the overview takes organization.read, which every role holds. Renaming takes organization.update, held by Admins and System admins.
  • Deactivating and reactivating take organization.deactivate and are for the owner only. An Admin who is not the owner sees a line saying the action is reserved for the owner. A custom role can never hold this permission.
  • Not sure whether you are the owner? The top card of Settings says You are the owner next to your name, or your role if you are not. To hand ownership to another admin, see Invite and manage members.
  • Before deactivating, tell your team and read the notes below on what stops. Take a copy of your configuration first if you want one, as described in Move configuration between servers.

Walk through it#

  1. Read the overview

    Open Settings. The top card shows the organization's name with an Active or Deactivated badge, when it was created and your own role. Below it are three counters for Members, Projects and Environments, and each one links to the page that manages it.

    The top of Settings for the owner. The three counters link to Members, Projects and Environments.
    You should see. The counters match what you see on the Members, Projects and Environments pages.
  2. Find a setting

    Under the card, the settings hub groups links such as Projects, Environments, Segments, Alert rules, Members, API keys and Audit logs. Type in Find a setting to narrow them, for example “keys”, “members” or “alerts”. A link only appears when your role can read the page behind it, so a Viewer sees fewer links than an Admin.

  3. Rename it

    Choose the pencil button (Rename organization) next to the name, type the new name and choose Save. Press Escape or choose Cancel to leave without saving.

    Rules for the name
    RuleLimitDescription
    Length2 to 100 charactersThe form shows “Use 2 to 100 characters.” and keeps Save off until the name fits.
    SpacesCollapsedRuns of spaces are collapsed to one and the ends are trimmed, so “ Acme Inc ” and “Acme Inc” are the same name.
    Same nameNo changeSaving the name it already has changes nothing and writes no audit entry.
    Renaming in place. Save stays off until the name changed and fits 2 to 100 characters.

    The name is a display label. Links, keys and SDK settings do not depend on it, so a rename never breaks anything.

    You should see. The heading shows the new name, and the audit log has an organization.updated entry with the old and new name.
  4. Look at how the server is set up

    If you can rename the organization, Settings also shows a collapsed System card. Its badge says Looks good or how many things there are to check. Open it to see any notices, a live check of the instance health, and the runtime, database, background scheduler, rate limiting, self-approval of releases, metrics collection and whether the Prometheus endpoint is on, in three groups. Each row names the environment variable behind it, and you can click the name to copy it. The values are read-only: you change them by editing the variables and redeploying, as described in Run FlagSwift in production.

  5. Deactivate it, only if you must

    At the bottom of Settings the owner sees Deactivate organization. Choose it and confirm in the dialog titled Deactivate this organization?. Nothing is deleted.

    What stops and what keeps working while deactivated
    AreaDescription
    Sign-inEveryone except the owner is refused with “Your organization is deactivated. Ask its owner to reactivate it, then sign in again.” and the code ORG_DEACTIVATED. The check happens after the password is verified, so it reveals nothing to someone guessing.
    SessionsAll sessions end at once, so people who were signed in are signed out.
    Console and Dashboard APICalls are refused with 403 and the code ORG_DEACTIVATED and the message “This organization is deactivated. Its owner can reactivate it.” The only calls that still work are reading the organization and the owner reactivating it.
    API keysEvery key stops resolving, so evaluation calls are refused until the owner reactivates.
    Your dataFlags, keys, members, segments, history and the audit log stay exactly as they were.
    The deactivation card at the very bottom of Settings, as the owner sees it. After deactivating, it reads Organization deactivated and offers Reactivate organization instead.

    SDKs fall back

    Server SDKs keep their last configuration and client SDKs their cache, so users may not notice at first. An SDK with nothing cached uses the default values in your code. Treat deactivation as a planned outage for anything that starts cold.
    You should see. The badge changes to Deactivated, the card at the bottom reads Organization deactivated with the time, and the audit log records organization.deactivated.
  6. Reactivate it

    The owner signs in, opens Settings and chooses Reactivate organization, then confirms Reactivate this organization?. Members can sign in again, keys resume serving flags and everything is as it was. Server SDKs pick up changes on their next fetch.

    You should see. The badge returns to Active and the audit log records organization.reactivated.

Ownership matters here

If the owner has left, move ownership to another admin first. Only the owner can reactivate, and nobody else can sign in while it is off.

Do it with the API#

Dashboard calls take a session cookie, not an API key. Sign in with POST /api/auth/login and pass the auth_session cookie.

Read, rename and switch off
# Read the overview (organization.read)
curl -s -b "auth_session=$SESSION" https://flags.example.com/api/organization

# Rename (organization.update)
curl -s -b "auth_session=$SESSION" -X PATCH https://flags.example.com/api/organization \
  -H "Content-Type: application/json" \
  -d '{"name":"Acme Platform"}'

# Deactivate and reactivate (owner only)
curl -s -b "auth_session=$SESSION" -X POST https://flags.example.com/api/organization/deactivate
curl -s -b "auth_session=$SESSION" -X POST https://flags.example.com/api/organization/reactivate

Every call is described in the Organization API: rename, deactivate and reactivate.

Troubleshooting#

Problems and fixes
SymptomDescription
Only the owner can deactivate or reactivate the organizationYou are an Admin but not the owner. Ask the owner, or have the owner transfer ownership to you first.
This organization is already active (or already deactivated)Someone else already made the change, or the page is stale. Reload Settings and check the badge.
Use 2 to 100 charactersThe name is too short or too long once spaces are collapsed. Shorten it, or add a character.
There is no pencil next to the nameYour role lacks organization.update. Ask an Admin to rename it.
Members get ORG_DEACTIVATED and cannot sign inThe organization is deactivated. The owner signs in, opens Settings and chooses Reactivate organization.
Apps keep serving flags after deactivationSDKs keep their last configuration or cache. Evaluation calls with a key are refused, but the SDK does not fail loudly. It will fall back to defaults once its cache is gone.

Good habits#

  • Name the organization after your company or team, because it is shown to everyone you invite and in invitation emails.
  • Keep at least two admins, and know who the owner is. Reactivation is the one thing nobody else can do.
  • Prefer archiving a project or revoking a key to deactivating the whole organization. Deactivation affects everyone and every key at once.
  • Check the organization.* entries in the audit log after any change, so renames and deactivations are tied to a person and a time.

What to check#

  • The new name shows in the Settings card and in the audit log as organization.updated.
  • After a deactivation test, the badge returns to Active and members can sign in again.
  • An SDK request with a key succeeds after reactivation.