Vault API

The Vault provides encrypted storage for sensitive data within Hippocortex. It solves a common problem in AI agent systems: agents frequently encounter secrets (API keys, database credentials, tokens) during their work. Without a vault, these secrets end up stored in plain text inside event histories and memory artifacts.

Hippocortex's Vault uses AES-256-GCM envelope encryption. Each secret gets its own Data Encryption Key (DEK), which is wrapped with a Key Encryption Key (KEK). Raw secret values are never stored in plain text. The Vault also integrates with the event pipeline: the API gateway automatically detects secrets in incoming payloads and can redact them, storing the real value in the Vault and replacing it with a reference.

All Vault operations require JWT authentication (not API keys).

Concepts

Vaults are containers for secrets. Each vault has a name, description, and sensitivity level. You might have separate vaults for "Production Secrets," "Development Keys," and "Third-Party Tokens."

Items are individual secrets stored within a vault. Each item has a name, an encrypted value, an optional type classification, and metadata.

Sensitivity levels (low, medium, high, critical) control access policies and audit granularity. Higher sensitivity items generate more detailed audit logs.

POST /v1/vaults

Create a new vault.

curl -X POST https://api.hippocortex.dev/v1/vaults \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production Secrets",
    "description": "API keys and credentials for production services",
    "sensitivity": "high"
  }'

Field	Type	Required	Default	Description
name	string	Yes	-	Vault name
description	string	No	-	Vault description
sensitivity	string	No	medium	low, medium, high, critical

GET /v1/vaults

List all vaults accessible to the authenticated user.

curl https://api.hippocortex.dev/v1/vaults \
  -H "Authorization: Bearer <jwt>"

POST /v1/vaults/:vaultId/items

Store a secret. The value is encrypted before storage and can only be retrieved with appropriate permissions.

curl -X POST https://api.hippocortex.dev/v1/vaults/vault-abc123/items \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Stripe API Key",
    "value": "sk_live_abc123...",
    "type": "api_key",
    "metadata": { "service": "stripe", "environment": "production" }
  }'

Field	Type	Required	Description
name	string	Yes	Item name
value	string	Yes	Secret value (will be encrypted)
type	string	No	Classification (e.g., api_key, password, token)
metadata	object	No	Additional context

GET /v1/vaults/:vaultId/items/:itemId

Retrieve a secret. This operation is audited and requires appropriate permissions.

curl https://api.hippocortex.dev/v1/vaults/vault-abc123/items/item-xyz789 \
  -H "Authorization: Bearer <jwt>"

The decrypted value is included in the response. Access is logged in the audit trail.

Automatic Secret Detection

The API gateway scans incoming capture payloads for patterns that look like secrets (API keys, connection strings, tokens). When a secret is detected:

1. The secret value is extracted and stored in the Vault
2. The payload is modified to replace the secret with a vault reference
3. The event is stored with the redacted payload

This happens transparently. Your agent captures events normally, and secrets are protected automatically.

Audit Trail

All vault operations (create vault, store secret, retrieve secret, delete) are recorded in the audit log with actor identity, timestamp, and operation details. See Audit Logs for more.