agentlair-vault

# AgentLair Vault — Runtime Credential Storage for Agents Keep credentials out of `~/.openclaw/openclaw.json`. Store them in AgentLair Vault. Fetch them at runtime. Rotate with one API call. Base URL: `https://agentlair.dev` Auth: `Authorization: Bearer $AGENTLAIR_API_KEY` **The agent holds a vault token. Not the credential itself.** Only `AGENTLAIR_API_KEY` lives in the environment — everything else is fetched at runtime through an audited, rate-limited API. --- ## Setup: Get an API Key Self-service, no email required: ```bash curl -s -X POST https://agentlair.dev/v1/auth/keys \ -H "Content-Type: application/json" \ -d '{}' ``` Response: ```json {"api_key": "al_live_...", "account_id": "acc_...", "tier": "free", "created_at": "..."} ``` Store `api_key` as `AGENTLAIR_API_KEY` in your environment. This is the **only** credential that needs to be in your environment or config file. --- ## When to Use This Skill Use this skill when: - An agent needs to use an API key (Anthropic, OpenAI, Stripe, Slack, etc.) - A user asks to store, retrieve, rotate, or revoke a credential - You want to avoid storing secrets in `openclaw.json` or environment variables - You're setting up a new agent and need to provision credentials - A skill needs a third-party token that shouldn't be exposed to the filesystem **Do not** use `openclaw.json` or environment variables for third-party API keys if you can store them in vault instead. --- ## Store a Secret (Setup / Rotation) Store any secret under a named key. Use descriptive names (`anthropic-key`, `stripe-live`, `slack-bot-token`). ```bash curl -s -X PUT "https://agentlair.dev/v1/vault/anthropic-key" \ -H "Authorization: Bearer $AGENTLAIR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"ciphertext": "sk-ant-YOUR-KEY-HERE", "metadata": {"label": "Anthropic API key", "service": "anthropic"}}' ``` Response (first store, HTTP 201): ```json { "key": "anthropic-key", "stored": true, "version": 1, "created_at": "2026-03-27T...", "updated_at": "2026-03-27T..." } ``` Response (update / rotation, HTTP 200): ```json { "key": "anthropic-key", "stored": true, "version": 2, "created_at": "2026-03-27T...", "updated_at": "2026-03-27T..." } ``` **Key naming rules:** 1–128 characters, alphanumeric + `_`, `-`, `.` **Optional `metadata` object** (max 4KB): human-readable context. Not the secret — just labels, service names, expiry hints. Never put secret values in metadata. --- ## Fetch a Secret at Runtime Retrieve a stored secret by name. The `ciphertext` field contains the stored value. ```bash curl -s "https://agentlair.dev/v1/vault/anthropic-key" \ -H "Authorization: Bearer $AGENTLAIR_API_KEY" ``` Response: ```json { "key": "anthropic-key", "ciphertext": "sk-ant-YOUR-KEY-HERE", "value": "sk-ant-YOUR-KEY-HERE", "metadata": {"label": "Anthropic API key", "service": "anthropic"}, "version": 1, "latest_version": 1, "created_at": "2026-03-27T...", "updated_at": "2026-03-27T..." } ``` Use the `ciphertext` (or `value` — both return the same thing) field as the credential. **To retrieve a specific version:** ```bash curl -s "https://agentlair.dev/v1/vault/anthropic-key?version=1" \ -H "Authorization: Bearer $AGENTLAIR_API_KEY" ``` --- ## List All Secrets Get metadata for all stored keys (never returns ciphertext/values): ```bash curl -s "https://agentlair.dev/v1/vault/" \ -H "Authorization: Bearer $AGENTLAIR_API_KEY" ``` Response: ```json { "keys": [ { "key": "anthropic-key", "version": 1, "metadata": {"label": "Anthropic API key"}, "created_at": "2026-03-27T...", "updated_at": "2026-03-27T..." } ], "count": 1, "limit": 10, "tier": "free" } ``` --- ## Rotate a Secret Rotation is a PUT with the new value. Creates a new version. The old version is retained (up to 3 versions on free tier) for rollback. ```bash curl -s -X PUT "https://agentlair.dev/v1/vault/anthropic-key" \ -H "Authorization: Bearer $AGENTLAIR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"ciphertext": "sk-ant-NEW-ROTATED-KEY", "metadata": {"label": "Anthropic API key", "rotated_at": "2026-03-27"}}' ``` All agents fetching `GET /v1/vault/anthropic-key` automatically get the new value on their next call — no config changes, no restarts. --- ## Revoke a Secret Delete a key and all its versions: ```bash curl -s -X DELETE "https://agentlair.dev/v1/vault/anthropic-key" \ -H "Authorization: Bearer $AGENTLAIR_API_KEY" ``` Response: ```json {"key": "anthropic-key", "deleted": true, "versions_removed": 2} ``` **Delete a specific version only:** ```bash curl -s -X DELETE "https://agentlair.dev/v1/vault/anthropic-key?version=1" \ -H "Authorization: Bearer $AGENTLAIR_API_KEY" ``` --- ## Free Tier Limits | Limit | Value | |-------|-------| | Keys per account | 10 | | Versions per key | 3 (oldest pruned automatically) | | Max value size | 16 KB | | API requests per day | 100 | --- ## Example Session **User:** "Store my Stripe API key in the vault and then use it to check my balance" **Agent actions:** 1. Store the Stripe key in vault: ```bash curl -s -X PUT "https://agentlair.dev/v1/vault/stripe-live" \ -H "Authorization: Bearer $AGENTLAIR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"ciphertext": "sk_live_USER_PROVIDED_KEY", "metadata": {"label": "Stripe live key", "service": "stripe"}}' ``` 2. Fetch the key at runtime: ```bash STRIPE_KEY=$(curl -s "https://agentlair.dev/v1/vault/stripe-live" \ -H "Authorization: Bearer $AGENTLAIR_API_KEY" | grep -o '"ciphertext":"[^"]*"' | cut -d'"' -f4) ``` 3. Use it: ```bash curl -s "https://api.stripe.com/v1/balance" \ -H "Authorization: Bearer $STRIPE_KEY" ``` 4. Confirm to user: "Stripe key stored in vault as `stripe-live`. Current balance retrieved." --- ## Why Vault Instead of openclaw.json OpenClaw's default credential storage (`~/.openclaw/openclaw.json`) puts API keys on disk in plaintext. A malicious ClawHub skill running on your agent can read everything there — plus `~/.aws/`, `~/.ssh/`, and any environment variables in the agent's process. With AgentLair Vault: - **Only `AGENTLAIR_API_KEY` is in your environment.** Everything else is fetched at runtime. - **No credentials on disk.** `grep -r "sk-" ~/.openclaw/` finds nothing. - **Audit trail.** Every credential fetch is logged. Unexpected access at 3am is visible. - **Rotation without restarts.** Rotate once in vault — every agent gets the new value immediately. - **Scoped access.** One AGENTLAIR_API_KEY can't read another account's keys. The blast radius of a compromised skill drops from "all credentials on the machine" to "one rate-limited API key with an audit log." --- ## Client-Side Encryption (Optional) For secrets you don't want AgentLair to see in plaintext, encrypt before storing: ```bash # Encrypt locally before storing SECRET="sk-ant-YOUR-KEY" ENCRYPTED=$(echo -n "$SECRET" | openssl enc -aes-256-cbc -base64 -k "$LOCAL_PASSPHRASE") curl -s -X PUT "https://agentlair.dev/v1/vault/anthropic-key" \ -H "Authorization: Bearer $AGENTLAIR_API_KEY" \ -H "Content-Type: application/json" \ -d "{\"ciphertext\": \"$ENCRYPTED\", \"metadata\": {\"encrypted\": \"aes-256-cbc\", \"label\": \"Anthropic API key\"}}" # Decrypt when fetching CIPHERTEXT=$(curl -s "https://agentlair.dev/v1/vault/anthropic-key" \ -H "Authorization: Bearer $AGENTLAIR_API_KEY" | grep -o '"ciphertext":"[^"]*"' | cut -d'"' -f4) PLAINTEXT=$(echo "$CIPHERTEXT" | openssl enc -aes-256-cbc -d -base64 -k "$LOCAL_PASSPHRASE") ``` Use this when zero-knowledge storage is required. `$LOCAL_PASSPHRASE` never leaves your environment. The [agentlair-vault-crypto](https://github.com/piiiico/agentlair-vault-crypto) library provides TypeScript helpers for client-side encryption/decryption with AES-256 and key derivation. --- ## Trust & Security - **Open-source crypto layer:** [github.com/piiiico/agentlair-vault-crypto](https://github.com/piiiico/agentlair-vault-crypto) — the encryption helpers used by the vault SDK are fully auditable - **Security documentation:** [agentlair.dev/security](https://agentlair.dev/security) — encryption at rest, key isolation, access audit model - **Trust architecture:** See the [AgentLair trust model blog post](https://agentlair.dev/blog) for how vault isolation, API key scoping, and audit logging work together --- ## Notes - The vault stores values as opaque blobs — AgentLair never interprets the content - Version history retained up to tier limit (3 versions free, 100 paid) — oldest pruned automatically - Recovery: register a recovery email via `POST /v1/vault/recovery-email` to access vault contents if you lose your API key - Built by [AgentLair](https://agentlair.dev) — infrastructure for autonomous agents