> For the complete documentation index, see [llms.txt](https://docs.kyvvu.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.kyvvu.com/platform/organizations.md). # Organizations & Access **What you'll learn:** How workspaces, organizations, members, and access control work in the Kyvvu platform. *** ## Workspaces Every Kyvvu account acts inside a **workspace**. Signing up creates your **personal workspace** automatically — yours alone, with nobody else in it — and you may also belong to any number of shared **organizations**. All data (agents, policies, logs, incidents, API keys) is isolated to the workspace you are currently in. There is no cross-workspace access. Switch with the selector at the top of the sidebar. The same dropdown is where you create a new organization: **+ New organization…** is its last entry, not a button hidden on a settings page. {% hint style="info" %} **Sharing an email domain with somebody no longer puts you in a workspace with them.** It once did. The only way into an organization is an invitation you accept, so signing up is repeatable and predictable: you always land in your own workspace, whatever your address. {% endhint %} ### Workspace identity A workspace has an **identifier** like `org_a1b2c3…` — opaque, stable, unique, and deliberately meaningless. Quote it to support. It never changes. Its **display name** is just a name. Change it freely; it is not unique and nothing keys on it. ## Member roles | Role | Capabilities | | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Owner** | Exactly one per organization. Everything an administrator can do, plus deleting the organization, naming a successor, and handing ownership to somebody who accepts it. **An owner cannot be demoted or removed by anyone else.** | | **Admin** | Manage workspace settings, invite / suspend / remove members, change roles, manage agents and policies. **Becoming an administrator is an offer you accept**, not something done to you. | | **Member** | Create agents, view data, manage own API keys. Cannot manage members or workspace settings. | Roles are explained in the dashboard behind the (i) beside the **Members** header. ## Invitations An invitation is the only thing that grants membership. 1. An administrator sends one from **Workspace → Members**. 2. The recipient opens the link and accepts. 3. **Accepting signs them in at the same moment** — there is no second magic link to wait for. Invitations can be resent and revoked. Somebody already signed in can accept as their current account rather than starting a new one. ## Ownership and succession Ownership is a two-party act: the current owner offers it, and the recipient accepts. Nobody is made owner without agreeing. An owner can also name a **successor** in advance, who accepts the nomination then rather than at the moment it matters. Only the owner may delete the organization. To leave one you own, hand it over first. ## Promoting a personal workspace A personal workspace can become an organization. Everything in it — agents, policies, logs, keys — stays exactly where it is, and you get a fresh personal workspace alongside it. Ask what promotion would expose before committing: `GET /api/v1/orgs/{org_id}/promotion` answers that, and the dashboard shows the same thing under **Workspace → General**. ## Suspension Nobody arrives unapproved — accepting an invitation makes you a member immediately, so there is nothing to approve. What an administrator *can* do is **suspend** a member. That stops one person acting in one organization without erasing that they were ever there. It does not stop the organization's agents, which keep running. Any administrator there can reinstate them. `kyvvu whoami` shows `✗ suspended in this workspace`. ### Registration cap Separately, the platform has an early-access registration cap (`KV_REGISTRATION_CAP`). An account created past it is marked **capped**: the account exists, but cannot sign in until **Kyvvu staff** release it. Nobody at your own organization can do that for you, and nothing is wrong with the account. If a colleague invited you, your membership is already real — only signing in is waiting. `kyvvu whoami` shows `✗ waiting to be admitted by Kyvvu`. {% hint style="warning" %} **Capped and suspended are different things with opposite remedies.** Capped is about the account and a platform that is full; only Kyvvu lifts it. Suspended is about one person in one organization; only an administrator there lifts it. `GET /api/v1/auth/me` publishes both, as `is_capped` and `is_suspended`. {% endhint %} ## Moving work between workspaces An agent is no longer tied to the person or credential that created it: an API key belongs to the workspace, survives its creator's account, and one key may serve several agents. Work can therefore change hands. Proposing a transfer moves agents, keys and repositories with their audit trail intact, and the receiving side sees **what enforcement would change** before consenting. Workspace-wide policies do not travel; each moved incident carries a self-contained snapshot of the policy it violated, so deleting the workspace it left cannot destroy it. ## Dashboard management 1. Open **Workspace** in the sidebar (it keeps the gear icon). 2. The **Members** tab — shown only in a shared organization — lists members, their roles and whether they are suspended. 3. From a member's row: **Change role** (offer administrator, which they accept, or return them to member), **Suspend / reinstate**, or **Remove**. ## API endpoints ### Workspaces | Method | Path | Description | | ------ | -------------------------------- | ----------------------------------------------- | | `GET` | `/api/v1/auth/workspaces` | List the workspaces this account can switch to. | | `POST` | `/api/v1/auth/workspaces/switch` | Switch the session to another workspace. | ### Organizations and members | Method | Path | Description | | ---------------------- | ----------------------------------------- | -------------------------------------- | | `GET` | `/api/v1/orgs` | List the organizations you belong to. | | `POST` | `/api/v1/orgs` | Create one. You become its owner. | | `GET` `PATCH` `DELETE` | `/api/v1/orgs/{org_id}` | Read, rename, or delete (owner only). | | `GET` | `/api/v1/orgs/{org_id}/members` | List members. | | `PATCH` | `/api/v1/orgs/{org_id}/members/{user_id}` | Change a role, or suspend / reinstate. | | `DELETE` | `/api/v1/orgs/{org_id}/members/{user_id}` | Remove a member. | | `DELETE` | `/api/v1/orgs/{org_id}/membership` | Leave an organization. | | `GET` | `/api/v1/orgs/{org_id}/stats` | Organization statistics. | ### Invitations | Method | Path | Description | | ------------ | ----------------------------------------------- | ------------------------------------------ | | `GET` `POST` | `/api/v1/orgs/{org_id}/invitations` | List or send. | | `POST` | `/api/v1/orgs/{org_id}/invitations/{id}/resend` | Resend. | | `DELETE` | `/api/v1/orgs/{org_id}/invitations/{id}` | Revoke. | | `POST` | `/api/v1/invitations/landing` | Open an invitation link (unauthenticated). | | `POST` | `/api/v1/invitations/accept` | Accept, and be signed in. | | `POST` | `/api/v1/invitations/accept-as-me` | Accept as the account already signed in. | ### Ownership, promotion and transfers | Method | Path | Description | | --------------- | ------------------------------------------------- | ----------------------------------------------------------- | | `GET` `POST` | `/api/v1/orgs/{org_id}/promotion` | What promoting would expose / promote a personal workspace. | | `POST` `DELETE` | `/api/v1/orgs/{org_id}/ownership/transfer` | Offer or withdraw ownership. | | `POST` | `/api/v1/orgs/{org_id}/ownership/transfer/accept` | Accept ownership. | | `PUT` | `/api/v1/orgs/{org_id}/successor` | Designate a successor. | | `POST` | `/api/v1/orgs/{org_id}/successor/respond` | Accept or decline the nomination. | | `POST` | `/api/v1/orgs/{org_id}/role-offer/respond` | Accept or decline an offered role. | | `GET` `POST` | `/api/v1/orgs/{org_id}/transfers` | List or propose moving work. | | `GET` `DELETE` | `/api/v1/orgs/{org_id}/transfers/{id}` | Read or withdraw a proposal. | | `POST` | `/api/v1/orgs/{org_id}/transfers/{id}/approve` | Approve a proposal. | ## API keys API keys authenticate agents with the platform. They belong to the **workspace**, not to the person who made them. Manage them via the dashboard (**Workspace → API Keys**) or the API: | Method | Path | Description | | -------- | -------------------------------- | --------------------------- | | `POST` | `/api/v1/auth/api-keys` | Create a new API key. | | `GET` | `/api/v1/auth/api-keys` | List API keys. | | `PATCH` | `/api/v1/auth/api-keys/{key_id}` | Enable/disable a key. | | `DELETE` | `/api/v1/auth/api-keys/{key_id}` | Revoke (soft-delete) a key. | API keys are prefixed with `KvKey-` and are shown only once at creation time. *** ## Next steps * [Dashboard Guide](/platform/dashboard.md) — navigate the platform * [Incident Management](/platform/incidents.md) — triage policy violations * [Configuration Reference](/deployment/configuration.md) — environment variables including the registration cap