RESPONSE schema: status codes, results, and value rules

Full reference for the keychain-auth RESPONSE envelope: status codes, reason field, results array structure, and when secret values are returned.

After the daemon processes a REQUEST, it writes a single RESPONSE line back on the same connection. Your client reads until the newline, parses the JSON, and inspects status to determine whether to proceed or handle an error.

Field reference

type · string · required

Always "RESPONSE". You can use this field to validate that you are reading a response envelope and not a stale or malformed message.

status · string · required

The outcome of the request. One of:

• "success" — the operation completed. Check results for output.
• "denied" — the daemon rejected the request for a policy reason. Check reason for the specific code.
• "error" — a lower-level failure occurred (bad JSON, OS keychain backend error). Check reason for the specific code.

reason · string

A machine-readable reason code. Set whenever status is "denied" or "error". Omitted on "success". See error codes for the full list and recommended handling.

results · array

An array of result objects returned for read and search operations. Empty or omitted for write, delete, and any non-success response.

Show result object fields

target · string

The key name.

value · string

The plaintext secret value. Only populated on authorized read operations. Never present on search results.

attributes · object

Key-value string metadata associated with the secret, if any was stored at write time.

value is never populated in search results, even when the search succeeds and returns targets. This is intentional: search is a discovery operation, not a retrieval operation. To read actual secret values, you must issue explicit read requests for the specific targets you want. This design limits the blast radius of a compromised binary to only the keys it explicitly requests.

Examples

Successful read

A read request that found both requested keys:

{
  "type": "RESPONSE",
  "status": "success",
  "results": [
    {
      "target": "prod-api-key",
      "value": "sk-live-abc123",
      "attributes": {
        "environment": "production"
      }
    },
    {
      "target": "prod-db-password",
      "value": "s3cr3t-db-pass",
      "attributes": {
        "environment": "production"
      }
    }
  ]
}

Successful search (no values)

A search response returns target names and attributes only — value is absent from every result:

{
  "type": "RESPONSE",
  "status": "success",
  "results": [
    {
      "target": "proj_123:production:DATABASE_URL",
      "attributes": {
        "environment": "production"
      }
    },
    {
      "target": "proj_123:production:STRIPE_KEY",
      "attributes": {
        "environment": "production"
      }
    }
  ]
}

Successful write or delete

Write and delete operations return an empty results array on success:

{
  "type": "RESPONSE",
  "status": "success",
  "results": []
}

Denied response

The daemon rejected the request due to a policy violation:

{
  "type": "RESPONSE",
  "status": "denied",
  "reason": "service_not_allowed"
}

Error response

A lower-level failure occurred (for example, the OS keychain was locked):

{
  "type": "RESPONSE",
  "status": "error",
  "reason": "internal_error"
}

Handling responses in your client

Check status first, then branch:

{
  "type": "RESPONSE",
  "status": "denied",
  "reason": "unregistered_binary_pending_approval"
}

When you receive "status": "denied" with reason unregistered_binary_pending_approval, the daemon has already closed the socket. Do not attempt to send further requests — the connection is gone. Surface a clear message to your user explaining that the binary needs to be approved via keychain-auth approve <hash>.

Always read and handle reason even on "status": "error". The internal_error code indicates a backend failure (locked keychain, lost dbus session), which may be transient and worth retrying after a short delay.