/org-management

name: org-management
description: "Manages organizations, billing, users, and authentication on Control Plane. Use when the user asks about creating an org, billing, inviting users, SSO or SAML login, CLI profiles, switching orgs, or service accounts."

Organization & User Management

> **Tool availability:** `update_org`, `configure_external_logging`, `invite_user_to_org`, `edit_group`, and `add_key_to_service_account` need `?toolsets=full`; reconnect with it or use the CLI.

An **org** is the top-level isolation boundary: every GVC, workload, secret, policy, image, domain, user, group, and service account lives inside one, with no cross-org sharing. An org **cannot be renamed or deleted** once created (every DELETE on `/org` returns 405) and its name is **globally unique** across all of Control Plane — so the first job is choosing a name you can live with permanently.

Organization

| Rule | Detail | |:---|:---| | Name charset | Lowercase letters, digits, hyphens; **must start with a letter**, cannot end with a hyphen; max 64 chars | | Reserved names | Cannot be `index`; cannot start with `xserve-` | | Uniqueness | Globally unique across the whole platform (DB-enforced), not per billing account | | Immutability | Name is unmodifiable; the org cannot be deleted — plan the name carefully |

**Create an org** (requires the `org_creator` or `billing_admin` role on a billing account — enforced by the billing service, not org policy):

cpln org create --name ORG --accountId BILLING_ACCOUNT_ID \
  --invitee admin@example.com --invitee dev@example.com

`--name`, `--accountId`, and `--invitee` (repeatable) are all required; invitees join the `superusers` group. Optional: `--description`, `--tag key=value`. Console path: **Create**, then **Org**. The **first** billing account can only be created in the Console.

Org-wide settings

Read with `mcp__cpln__get_resource` (kind `org`); change with `mcp__cpln__update_org` (a merge/PATCH — pass only the blocks you change). Settings apply to every member and workload.

| Spec block | Set via `update_org`? | Notes | |:---|:---|:---| | `sessionTimeoutSeconds` | Yes | Console inactivity timeout; minimum **900** (15 min); no platform default | | `authConfig.domainAutoMembers` | Yes | Email domains whose users auto-join the org | | `authConfig.samlOnly` | Yes | Boolean, **no default** (unset = off); require SAML for all members | | `observability.*RetentionDays` | Yes | `logs`/`metrics`/`traces`, 0–3650, **default 30**; `0` turns that stream **off** | | `observability.defaultAlertEmails` | Yes | Default Grafana alert recipients | | `security.threatDetection` | Yes | Forward detected threats to a syslog target (`enabled` + optional `minimumSeverity` + syslog host/port) | | `logging` / `extraLogging` | **No** | Use `mcp__cpln__configure_external_logging` — see **external-logging** | | `tracing` | **No** | Escape hatch: `mcp__cpln__get_resource` (kind `org`, `schema: true`), author the block, `cpln apply -f org.yaml` |

Billing

Billing accounts (invoices, payment methods, spend alerts, org creation) are managed **only in the Console** — there is no MCP tool or `cpln` command for them. Billing roles and org policies are **independent IAM systems**: a `billing_admin` has zero implicit permission on any org resource.

| Billing role | Grants | |:---|:---| | `billing_admin` | Full billing access: settings, invoices, billing users | | `billing_viewer` | Read-only billing access | | `org_creator` | Create orgs under the account |

Users

**Invite** with `mcp__cpln__invite_user_to_org` (`email` required, `groupName` optional) or `cpln user invite --email EMAIL --group GROUP`. The user gets an onboarding email; **pending invites are viewable/cancellable only in the Console** (Users, then Pending Invites) — no MCP/CLI list exists. Up to 10 invites per API request; the Console also bulk-invites from a CSV.

> **A group chosen at invite time is applied only when the user accepts** — not immediately, and the invite still succeeds if the group can't be set. To place someone in a group right away, or fix one that didn't stick, use `mcp__cpln__edit_group`.

Read/delete users with the generic tools (no typed read tool): `mcp__cpln__get_resource` / `list_resources` / `delete_resource` (kind `user`), or `cpln user get` / `cpln user delete EMAIL`. Tags have no typed tool — use `cpln user update EMAIL --set tags.key=value`. Deleting a user is destructive: check their group memberships and policy bindings first.

**User permissions** (for policies):

| Permission | Implies | |:---|:---| | `view` | — | | `edit` | `view` | | `delete` | — | | `invite` | — | | `impersonate` | — | | `manage` | all of the above |

Groups & service accounts

Groups aggregate **users and service accounts only** (member links `//user/EMAIL`, `//serviceaccount/NAME`; max 200). `mcp__cpln__edit_group` is the **single** mutation tool — it edits description/tags and adds/removes members; there is no separate add-member tool. Dynamic membership (`memberQuery`, `identityMatcher`) and policy mechanics live in **access-control**.

Service-account **names are immutable** (rename = delete + recreate, which invalidates every key). `mcp__cpln__add_key_to_service_account` creates the SA if absent (`serviceAccountName`, optional `keyDescription` ≤250 chars and `groupName`) and returns the Console keys page, where the user adds the key and sees it **once**; the value never passes through the chat. CLI fallback: `cpln serviceaccount create --name NAME` then `cpln serviceaccount add-key NAME --description "..."` (the CLI does **not** auto-create the SA; `--description` is required).

Profiles, tokens & auth

Profiles store CLI credentials and default context (org, GVC). A user can belong to many orgs; switch the active one with the Console org selector, the `--org` flag or `CPLN_ORG`, or a per-org profile.

| Action | Command | |:---|:---| | Interactive login (creates `default` profil