AgentLair Vault

Store and fetch credentials securely at runtime via AgentLair Vault REST API. Use this skill when an agent needs to read an API key, store a secret, rotate credentials, or avoid putting secrets in openclaw.json. Credentials stay encrypted in the vault. Only AGENTLAIR_API_KEY lives in your environment. Use instead of environment variables or openclaw.json for third-party API keys, tokens, and secrets.

intent

This skill lets agents and users store, retrieve, rotate, and revoke credentials at runtime without exposing secrets to disk, config files, or the process environment. Use it when an agent needs access to third-party API keys (Anthropic, OpenAI, Stripe, Slack, etc.), when a user asks to store or rotate a credential, or when setting up a new agent and need to provision secrets without writing them to openclaw.json. The vault holds all credentials encrypted. The agent only ever holds one token: AGENTLAIR_API_KEY. On fetch, the agent gets the plaintext credential from the vault API, uses it, and discards it (credential does not persist in memory or on disk).

inputs

• AGENTLAIR_API_KEY (environment variable, required): Bearer token for all vault API calls. Obtain it via self-service signup at https://agentlair.dev/v1/auth/keys (no email required). Store this as an env var or in secure config. This is the only credential that should live in your environment.
• Base URL: https://agentlair.dev
• HTTP client: curl (or equivalent; all examples use curl)
• Network access: agent must be able to reach https://agentlair.dev over HTTPS
• Rate limits (free tier): 100 API requests per day. Paid tiers have higher limits. Exceeding limits returns HTTP 429 (Too Many Requests); retry with exponential backoff.
• Vault capacity (free tier): 10 keys per account, 3 versions per key, 16 KB per value. Oldest versions auto-prune when limit exceeded. Paid tiers increase all limits.

procedure

step 1: obtain an api key (one-time setup)

inputs: none (self-service, no auth required)

action: POST to the auth endpoint to generate a new API key.

curl -s -X POST https://agentlair.dev/v1/auth/keys \
  -H "Content-Type: application/json" \
  -d '{}'

outputs: JSON response containing api_key (string, format al_live_...), account_id, tier, and created_at.

{
  "api_key": "al_live_...",
  "account_id": "acc_...",
  "tier": "free",
  "created_at": "2026-03-27T..."
}

Store the api_key value as AGENTLAIR_API_KEY in your environment immediately. Do not share this key. If compromised, register a recovery email and revoke the key via the dashboard.

edge cases:

• If the request times out (network unreachable), retry up to 3 times with 5-second delays.
• Free tier signup is instant; no email verification required. Paid tier upgrades require account confirmation.

step 2: store a credential in the vault

inputs:

• AGENTLAIR_API_KEY (from step 1)
• key_name (string, 1-128 characters, alphanumeric + _, -, .): descriptive name for the credential (e.g., anthropic-key, stripe-live, slack-bot-token)
• credential_value (string): the actual API key, token, or secret to store
• metadata (optional, JSON object, max 4 KB): human-readable labels and context (e.g., {"label": "Anthropic API key", "service": "anthropic"}). Never put secret values in metadata.

action: PUT the credential to the vault endpoint.

curl -s -X PUT "https://agentlair.dev/v1/vault/KEYNAME" \
  -H "Authorization: Bearer $AGENTLAIR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ciphertext": "CREDENTIAL_VALUE", "metadata": {...}}'

Replace KEYNAME with your key name (e.g., anthropic-key) and CREDENTIAL_VALUE with the actual secret.

outputs:

• HTTP 201 (new key): JSON response with key, stored: true, version: 1, created_at, updated_at.
• HTTP 200 (key already exists, updating): JSON response with incremented version (e.g., version: 2).

{
  "key": "anthropic-key",
  "stored": true,
  "version": 1,
  "created_at": "2026-03-27T...",
  "updated_at": "2026-03-27T..."
}

edge cases:

• If key name exceeds 128 characters or uses invalid characters (not alphanumeric, _, -, .), vault returns HTTP 400 (Bad Request).
• If metadata exceeds 4 KB, returns HTTP 413 (Payload Too Large).
• If credential value exceeds 16 KB (free tier), returns HTTP 413.
• If account has hit key limit (10 free, more on paid), returns HTTP 507 (Insufficient Storage).
• If AGENTLAIR_API_KEY is invalid or expired, returns HTTP 401 (Unauthorized).
• Network timeout (e.g., client timeout set to 10s): retry up to 3 times with exponential backoff.

step 3: fetch a credential at runtime

inputs:

• AGENTLAIR_API_KEY
• key_name (string): name of the stored credential (e.g., anthropic-key)
• version (optional, integer): specific version to fetch. If omitted, fetches latest.

action: GET the credential from the vault.

curl -s "https://agentlair.dev/v1/vault/KEYNAME" \
  -H "Authorization: Bearer $AGENTLAIR_API_KEY"

To fetch a specific version:

curl -s "https://agentlair.dev/v1/vault/KEYNAME?version=1" \
  -H "Authorization: Bearer $AGENTLAIR_API_KEY"

outputs: JSON response containing the credential in the ciphertext or value field (both return the same plaintext value), metadata, version info, and timestamps.

{
  "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..."
}

Extract the ciphertext (or value) field. Use it as your credential in the next API call.

edge cases:

• If key does not exist, returns HTTP 404 (Not Found).
• If version does not exist (e.g., asking for version 5 when only versions 1,2,3 exist), returns HTTP 404.
• If AGENTLAIR_API_KEY is invalid or revoked, returns HTTP 401.
• If rate limit exceeded (100 requests/day free tier), returns HTTP 429. Wait 60 seconds and retry.
• Network timeout: retry up to 3 times with exponential backoff (5s, 10s, 20s).

step 4: list all stored credentials (metadata only)

inputs:

• AGENTLAIR_API_KEY

action: GET the vault root endpoint.

curl -s "https://agentlair.dev/v1/vault/" \
  -H "Authorization: Bearer $AGENTLAIR_API_KEY"

outputs: JSON response with array of keys (metadata only, no ciphertext or values), count, tier limits.

{
  "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"
}

This endpoint never returns ciphertext or plaintext values, only metadata.

edge cases:

• If account has 0 keys, keys array is empty, count: 0.
• If account has more keys than the free tier limit allows listing in one response, pagination is available via ?offset=N&limit=M query params.
• If AGENTLAIR_API_KEY is invalid, returns HTTP 401.

step 5: rotate a credential

inputs:

• AGENTLAIR_API_KEY
• key_name (string): name of the credential to rotate
• new_credential_value (string): the new API key or token
• metadata (optional): updated metadata (e.g., {"rotated_at": "2026-03-27"})

action: PUT the new credential value to the same key endpoint. Vault auto-increments the version.

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"}}'

outputs: JSON response with incremented version and updated timestamps.

{
  "key": "anthropic-key",
  "stored": true,
  "version": 2,
  "created_at": "2026-03-27T...",
  "updated_at": "2026-03-27T..."
}

All agents or services fetching this key via GET will automatically receive the new value on their next call. No restarts or config changes required.

Old versions are retained (up to 3 on free tier, more on paid). Oldest version auto-prunes when limit is exceeded.

edge cases:

• If key does not exist, vault creates it (HTTP 201) instead of updating.
• If version count at limit (3 free), oldest version is pruned automatically.
• If new credential exceeds 16 KB (free tier), returns HTTP 413.
• If AGENTLAIR_API_KEY invalid, returns HTTP 401.

step 6: revoke or delete a credential

inputs:

• AGENTLAIR_API_KEY
• key_name (string): name of the credential to delete
• version (optional, integer): specific version to delete. If omitted, deletes all versions.

action: DELETE the credential from vault.

# Delete all versions of a key
curl -s -X DELETE "https://agentlair.dev/v1/vault/anthropic-key" \
  -H "Authorization: Bearer $AGENTLAIR_API_KEY"

To delete a specific version only:

curl -s -X DELETE "https://agentlair.dev/v1/vault/anthropic-key?version=1" \
  -H "Authorization: Bearer $AGENTLAIR_API_KEY"

outputs: JSON response confirming deletion.

{"key": "anthropic-key", "deleted": true, "versions_removed": 2}

Once deleted, the key and all its versions are unrecoverable. If you need to re-add it, store it again.

edge cases:

• If key does not exist, returns HTTP 404.
• If version does not exist, returns HTTP 404.
• If AGENTLAIR_API_KEY invalid, returns HTTP 401.
• Deletion is immediate and permanent. No soft delete.

decision points

if AGENTLAIR_API_KEY is not set in the environment: do not attempt any vault API calls. agent should raise an error ("AGENTLAIR_API_KEY not found in environment"). user must generate a key via step 1 and set it before proceeding.

if the vault returns HTTP 401 (Unauthorized): the AGENTLAIR_API_KEY is invalid, expired, or revoked. user must generate a new key. if a recovery email was registered, user can attempt account recovery via dashboard.

if the vault returns HTTP 404 (Not Found) when fetching a credential: the key does not exist or the specific version was pruned. check that the key name is spelled correctly. if intentional deletion occurred, the agent must ask the user to re-store the credential.

if the vault returns HTTP 429 (Too Many Requests): the account has exceeded its daily rate limit (100 requests/day free tier). agent should stop issuing vault requests immediately. suggest to user: wait 60 seconds or upgrade to a paid tier for higher limits. do not retry immediately.

if the vault returns HTTP 413 (Payload Too Large): the credential value or metadata exceeds the tier limit (16 KB value, 4 KB metadata on free tier). agent should reject the store request and ask user to provide a smaller value.

if the vault returns HTTP 507 (Insufficient Storage): the account has hit the key limit for the tier (10 free, more on paid). agent should not attempt to store new keys. user must delete unused keys or upgrade tier.

if network request times out (no response after 10 seconds): retry the request up to 3 times with exponential backoff (wait 5s, then 10s, then 20s between retries). if all 3 retries fail, agent should report to user: "vault unreachable; check network connectivity and try again later."

if the user asks to store a credential but does not provide a value: agent should ask the user to provide the credential before calling the vault.

if the user asks to fetch a credential that does not exist: agent should check the list endpoint first (step 4) to confirm available keys. if the key truly does not exist, inform the user that the key is not stored and ask if they want to store it.

if a credential has multiple versions and the user does not specify which version to use: fetch the latest version (omit the ?version= query param). display to the user which version is being used.

if the user requests client-side encryption (optional): encrypt the credential locally before sending it to the vault. store the encrypted blob as the ciphertext. when fetching, decrypt the ciphertext locally using the same passphrase. (see examples in optional section below.)

output contract

successful store (step 2):

• HTTP status: 201 (new) or 200 (update)
• response body: JSON with fields key, stored, version, created_at, updated_at
• side effect: credential is now encrypted and stored in agentlair vault; accessible via GET requests with same AGENTLAIR_API_KEY

successful fetch (step 3):

• HTTP status: 200
• response body: JSON with fields key, ciphertext (or value), metadata, version, latest_version, created_at, updated_at
• data format: ciphertext is a plaintext string (the actual credential value)

successful list (step 4):

• HTTP status: 200
• response body: JSON with keys (array of metadata objects, no secrets), count, limit, tier
• data format: each item in keys array has key (name), version, metadata, created_at, updated_at; no plaintext values

successful rotate (step 5):

• HTTP status: 200
• response body: JSON with key, stored, version (incremented), created_at, updated_at
• side effect: new credential is stored as latest version; previous version is retained (up to tier limit); all future fetches return the new value

successful delete (step 6):

• HTTP status: 200
• response body: JSON with key, deleted: true, versions_removed (count of deleted versions)
• side effect: key and all its versions are permanently removed from vault

error responses:

• HTTP 400: invalid key name or metadata format
• HTTP 401: AGENTLAIR_API_KEY invalid or expired
• HTTP 404: key or version not found
• HTTP 413: credential or metadata exceeds size limit
• HTTP 429: rate limit exceeded (free tier: 100 req/day)
• HTTP 507: account storage limit hit (free tier: 10 keys)
• HTTP 5xx: vault service error; retry later

outcome signal

user knows the skill worked when:

• after storing: agent confirms "credential stored in vault as keyname" and returns the HTTP 201 or 200 response. user can verify by listing keys (step 4) and seeing the new key in the output.
• after fetching: agent retrieves the credential, uses it to make a downstream API call (e.g., call Anthropic API, Stripe API), and reports the result. example: "fetched stripe-key from vault; current balance: $1,234.56."
• after rotating: agent confirms "credential rotated; new version is N" and all