REQUEST schema: actions, fields, and match modes

Full reference for the keychain-auth REQUEST envelope: all fields, supported actions, match modes, write alignment rules, and JSON examples.

A REQUEST message tells the daemon which keychain operation to perform, which service namespace to target, and which keys to act on. You send one JSON object per line and the daemon responds with a single RESPONSE on the same connection.

Field reference

type · string · required

Must be exactly "REQUEST". Any other value causes the daemon to return a malformed_request error.

action · string · required

The operation to perform. One of:

• "read" — retrieve plaintext values for the specified keys.
• "write" — store plaintext values for the specified keys.
• "delete" — remove the specified keys from the keychain.
• "search" — list matching key names without returning their values.

service · string · required

The keychain service namespace to operate in (for example, "aws", "openai", or "AgentSecrets"). Your binary’s policy must list this service in allowed_read_services or allowed_write_services depending on the action. The daemon enforces this per-connection; if the service is not in your policy the request is denied with service_not_allowed.

match · string

Controls how targets are interpreted. Defaults to "exact" when omitted.

• "exact" — each entry in targets is a full key name.
• "prefix" — each entry in targets is a prefix string; the daemon matches all keys that start with that prefix. Not allowed for "write".

Prefix operations on read and delete require your binary to have can_search: true in its policy, because the daemon must enumerate keys internally to resolve matches.

targets · string[] · required

The key identifiers to act on. Required for read, write, and delete. Optional for search — when provided on a search, entries act as prefix filters applied server-side.

For "match": "prefix", each entry is a prefix string (for example, "proj_123:production:").

values · string[]

Plaintext values to store. Required only when action is "write". Each entry corresponds by index to the entry at the same position in targets.

attributes · object

Arbitrary key-value string metadata to associate with keys or filter by during searches. All values must be strings.

Strict array alignment for writes: when action is "write", targets.length must equal values.length. If they differ, the daemon rejects the entire payload with malformed_request and no writes occur.

Restrictions summary

Rule	Details
"match": "prefix" not allowed on write	Prefix matching has no defined semantics for write operations.
Prefix read or delete requires can_search: true	The daemon must enumerate keys internally to resolve prefixes.
values required and aligned for write	targets.length must equal values.length.
All-or-nothing batch	If any target fails a policy check, the entire request is rejected before any keychain operation runs.

Examples

Read

Retrieve exact values for two keys:

{
  "type": "REQUEST",
  "action": "read",
  "service": "aws",
  "targets": ["prod-api-key", "prod-db-password"]
}

Retrieve all keys in a namespace by prefix (requires can_search: true):

{
  "type": "REQUEST",
  "action": "read",
  "service": "AgentSecrets",
  "match": "prefix",
  "targets": ["proj_123:production:"]
}

Write

Store two keys in a single round-trip:

{
  "type": "REQUEST",
  "action": "write",
  "service": "AgentSecrets",
  "targets": [
    "proj_123:production:DATABASE_URL",
    "proj_123:production:STRIPE_KEY"
  ],
  "values": [
    "postgres://prod-db.internal/app",
    "sk-live-abc123"
  ],
  "attributes": {
    "environment": "production",
    "managed-by": "deploy-tool"
  }
}

Delete

Delete specific keys by exact name:

{
  "type": "REQUEST",
  "action": "delete",
  "service": "AgentSecrets",
  "targets": [
    "proj_123:staging:OLD_API_KEY"
  ]
}

Delete all keys matching a prefix (requires can_search: true):

{
  "type": "REQUEST",
  "action": "delete",
  "service": "AgentSecrets",
  "match": "prefix",
  "targets": ["proj_123:staging:"]
}

Search

List all key names in a service namespace without retrieving values:

{
  "type": "REQUEST",
  "action": "search",
  "service": "AgentSecrets"
}

List only keys whose names start with a given prefix:

{
  "type": "REQUEST",
  "action": "search",
  "service": "AgentSecrets",
  "targets": ["proj_123:production:"]
}