Skip to content

Workspaces, 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.

Note

Sharing an email domain with somebody does not put you in a workspace with them. 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.

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 Rename the organization, invite / resend / revoke invitations, suspend and remove members, change roles, see, disable and revoke every API key in the workspace and deactivate any agent, and propose moving work to another workspace (or approve work arriving). Becoming an administrator is an offer you accept, not something done to you.
Member Everything below that is not listed for administrators: create agents and API keys, connect repositories, assign manifests, manage policies, read logs and incidents, generate reports. Can see and manage only their own API keys and deactivate only their own agents. Cannot manage members, invitations or the organization's settings.

Administrators do not have extra say over policies. Policies, manifest assignments and repositories are not gated by role: any member of the workspace can change them, and an administrator has no additional power there. The role checks in the platform are on members, invitations, organization settings, workspace transfers, API keys and agent deactivation, and nowhere else.

A suspended member holds their role but cannot act in that organization at all.

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.

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.

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.

A key may carry allowed_agent_keys, a non-empty list of agent keys it may act for; null (the default) allows every agent in the workspace. A key restricted this way is refused on every agent-key endpoint for any other agent.

Next steps