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.
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
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.
An administrator sends one from Workspace → Members.
The recipient opens the link and accepts.
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.
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
Open Workspace in the sidebar (it keeps the gear icon).
The Members tab — shown only in a shared organization — lists members, their roles and whether they are suspended.
From a member's row: Change role (offer administrator, which they accept, or return them to member), Suspend / reinstate, or Remove.
API endpoints
Workspaces
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
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
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
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:
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 — navigate the platform
Incident Management — triage policy violations
Configuration Reference — environment variables including the registration cap
Last updated