Agents and integrations authenticate to Kival with API keys owned by users. A key is not a separate Kival principal: it acts through its owner's authority and can only narrow that authority through scopes, workspace delegation, expiration, or revocation.
This page is about the credential boundary. For how agents should work with Kival knowledge, see Using Kival with agents.
Create credentials interactively
API keys are created and changed through an authenticated browser session, with fresh authentication required for security-sensitive operations. One API key cannot mint another.
The plaintext secret is returned when the key is created; Kival stores a hash rather than the reusable secret. Store the secret in the agent or integration's credential system at creation time.
A key can carry a label so its activity remains distinguishable in audit history.
Delegate only what is needed
API-key scopes are capability boundaries such as object read/write, graph read/write, attachments, events, realtime, access management, or global administration.
Write scopes satisfy their corresponding read scope, but unrelated capabilities remain separate. A scope can never grant authority the owning user does not already have.
Start with the smallest useful set. A read-only exploration agent, for example, generally does not need object-write or access-management capability.
Delegate workspaces explicitly
Workspace-scoped routes also require explicit workspace delegation on the key. Holding objects:read does not make every workspace the owner can access available to the credential.
This is particularly useful for agents: a key can represent a capable user while still being confined to the workspace where that agent is supposed to operate.
Preserve attribution
Object versions created through an API key are attributed to the owning user. Audit events can additionally retain the specific API key and its label, allowing activity from different agents or integrations to remain distinguishable.
Use separate labeled keys for separate automation boundaries instead of sharing one broad credential between unrelated systems.
Expire, rotate, and revoke
Keys can have an expiration time and can be revoked. Kival also tracks usage information such as last-used state.
Prefer replacement over indefinite credential reuse. Create a new narrowly scoped key, update the consumer, verify it is working, then revoke the old one. If a credential is suspected to be exposed, revoke it rather than relying only on downstream restrictions.
The server still applies the owner's current authorization on every new request. Removing the user's workspace or object access therefore removes that authority from the key as well.