Administration

Kival separates routine in-product administration from deployment-operator authority. Most day-to-day work belongs to global, workspace, group, or object administrators; kivald admin exists for bootstrap, provisioning, lifecycle, and recovery when browser authentication is unavailable.

Administrative layers

These layers overlap where broader roles intentionally imply narrower administrative authority.

Bootstrap and provision users

The first global administrator is created with the operator CLI. New users can likewise be provisioned before they have browser credentials.

Kival does not use normal passwords. A provisioned user enrolls a passkey to begin interactive use. Keep operator/database access restricted to the small set of people who actually need this recovery boundary.

User lifecycle and passkey recovery

Administrators can disable and later enable users without rewriting their historical authorship. Disabling a user prevents new authenticated activity while preserving the records they already contributed.

If a user loses access to their passkeys, an operator can issue recovery through kivald admin. Recovery can also revoke existing API keys when the situation calls for a broader credential reset.

Users normally manage their own passkeys and browser sessions from the authenticated application. Recovery is the exception, not the routine credential-management path.

Workspaces and groups

Global administrators can create and govern workspaces; workspace administrators manage participation inside the workspace and receive administrative authority over its objects.

Groups provide reusable membership sets that can be linked into workspaces and granted access to objects. Keep group membership, workspace participation, and object grants conceptually separate: each is an independent part of the effective-access calculation.

Object access

Object administrators can grant viewer, editor, or admin access directly to users or linked groups, update those grants, and revoke them.

Kival protects the final administrative path around an object so access changes do not accidentally leave it without manageable ownership. Use Access model for the underlying authorization rules and Working with others for normal sharing patterns.

API keys

API keys are user-owned credentials. Users create and manage them through fresh authenticated browser sessions, while administrators control the user's underlying account and access rather than routinely handling their secrets.

For agents and integrations, use separate labeled keys with narrow scopes, explicit workspace delegation, expiration where appropriate, and prompt revocation when no longer needed. See Agent access.

Audit and offboarding

Kival records auditable domain events across objects, access changes, memberships, groups, credentials, commentary, and other lifecycle operations. Event visibility follows administrative scope, with sensitive grant history requiring appropriate authority.

When someone leaves:

1. remove or revoke workspace participation where appropriate;

2. remove group memberships that should no longer apply;

3. disable the user when they should no longer authenticate;

4. revoke credentials that should stop working;

5. preserve authored history instead of trying to erase attribution.

The exact order can depend on the organization, but revoking future authority should not destroy the historical record of what the user contributed.

Keep operator access exceptional

kivald admin connects directly to PostgreSQL so bootstrap and recovery remain possible even when browser authentication is broken. That makes it a break-glass/operator surface, not a convenience replacement for normal administration.

Protect database credentials and host access accordingly, audit their use outside Kival where appropriate, and use the product's scoped administrative roles for ordinary work.