Items

An item is a stored credential. Every item belongs to a profile, inherits its storage mode, and carries a kind that suggests which fields are expected.

Schema

Field	Type	Description
`id`	text (PK)	Item ID
`organizationId`	text	Owning organization (the isolation boundary)
`profileId`	text \| null	Parent profile (`ON DELETE set null`)
`createdBy`	text \| null	User who created the row (audit metadata, not ownership; `ON DELETE set null`)
`label`	text	Cleartext display name
`kind`	text \| null	`login`, `api_key`, `token`, `json`, `certificate`, `ssh_key`, `opaque`
`tags`	jsonb	Array of strings (default `[]`)
`storageMode`	text	`zero_knowledge` or `server_managed` (inherited from profile)
`encryptedItemKey`	text \| null	DEK wrapped by root key; the 24-byte XChaCha20-Poly1305 wrap nonce is prepended into its first bytes (ZK only)
`ciphertext`	text \| null	Payload encrypted by DEK; the 24-byte content nonce is prepended into its first bytes (ZK only)
`serverCiphertext`	text \| null	AES-256-GCM ciphertext (server-managed only)
`serverIv`	text \| null	12-byte IV (server-managed only)
`serverKeyVersion`	integer \| null	Encryption-key version; also the AAD-epoch marker (1 = legacy no-AAD, ≥2 = AAD-bound, ≥3 = per-profile DEK) (server-managed only)
`cryptoVersion`	integer	Envelope format version (default `1`)
`contentVersion`	integer	Optimistic-concurrency counter (default `1`)
`deletedAt`	timestamptz \| null	Soft-delete timestamp

There is no separate contentNonce or keyNonce column — both nonces are prepended into the ciphertext/key fields. Labels and tags are stored in cleartext to allow listing without decryption.

The plaintext envelope

The plaintext that gets encrypted has a stable JSON shape:

{
  "v": 1,
  "label": "prod postgres",
  "kind": "login",
  "tags": ["prod", "db"],
  "notes": "Primary production database",
  "fields": {
    "host": "db.example.com",
    "port": 5432,
    "username": "app",
    "password": "s3cret"
  }
}

For zero-knowledge items the entire JSON is encrypted with the item DEK. For server-managed items it’s encrypted with AES-256-GCM by the API.

Kinds and standard fields

Each kind suggests the standard fields readers will look for. The fields themselves are free-form, but using the standard names enables single-field auto-delivery.

Kind	Standard fields
`login`	`username`, `email`, `password`, `url`, `totp_secret`
`api_key`	`value`, `key_id`, `key_secret`
`token`	`value`
`certificate`	`cert`, `key`, `chain`, `passphrase`
`ssh_key`	`private_key`, `public_key`, `passphrase`
`json`	(user-defined)
`opaque`	`value`

See Field delivery for the resolution rules when a reader requests a specific field.

Optimistic concurrency

Updates use contentVersion for optimistic concurrency. Pass the current version with the update; the server rejects stale writes with STALE_VERSION. Re-fetch and retry.

Lifecycle

[Created] → item.create
  │
  ├── [Updated] → item.update (contentVersion++)
  │
  └── [SoftDeleted] → item.delete (deletedAt set, ciphertext retained)

Soft-delete preserves the ciphertext but prevents future access. Permissions cascade-deny with result: cascade audit entries.

Listing

Both operators and agents can list items, but the responses differ:

GET /v1/items (session) returns metadata for every item the user can see in the active organization.
GET /v1/items (agent) returns metadata only for items the calling agent has at least one permission row on. Agents without grants get an empty list.

Neither endpoint returns secret data. To read a secret, call POST /v1/access/{itemId}/read (or reserve a mount with POST /v1/access/{itemId}/use) with the appropriate capability.

Overview

Concepts

Security

Workflows

Examples

Migration

Schema

The plaintext envelope

Kinds and standard fields

Optimistic concurrency

Lifecycle

Listing

​Schema

​The plaintext envelope

​Kinds and standard fields

​Optimistic concurrency

​Lifecycle

​Listing

​Related

Schema

The plaintext envelope

Kinds and standard fields

Optimistic concurrency

Lifecycle

Listing

Related