Vault API (v1)

This page describes the intended Vault API shape for storing and using generic secrets (API keys, tokens, arbitrary env vars) in Clawb.

Note: endpoint names may evolve. The core contract is stable: store secret sets, grant access, mint leases, and use secrets via proxy/injection.

Objects

Secret set

A named collection of key/value entries. Fields (conceptual):

id
workspace_id / org_id
human_owner_id (optional)
provider (string)
environment (string)
name (string)
created_at, updated_at
version

Grant

Permission for an agent to use a secret set. Fields (conceptual):

id
secret_set_id
agent_id
allowed_keys: "*" or an array allowlist
allowed_actions: e.g. proxy_use, mint_workflow_lease, export_plaintext (disabled by default)
expires_at (optional)

Lease

Short-lived capability token. Fields (conceptual):

lease_id
kind: request | workflow
expires_at
constraints (bound secret set, actions, optional key allowlist)

Create a secret set (KV)

curl -sS -X POST "https://api.clawb.ai/api/v1/vault/secret-sets" \
  -H "Content-Type: application/json" \
  -H "X-Clawb-Api-Key: ck_live_replace_me" \
  -d '{
    "provider": "stripe",
    "environment": "prod",
    "name": "billing-bot",
    "entries": {
      "STRIPE_SECRET_KEY": "sk_live_...",
      "STRIPE_WEBHOOK_SECRET": "whsec_..."
    }
  }'

from clawb_agent_sdk import ClawbClient

client = ClawbClient(base_url="https://api.clawb.ai/api")

secret_set = client.post(
    "/v1/vault/secret-sets",
    headers={"X-Clawb-Api-Key": "ck_live_replace_me"},
    json={
        "provider": "stripe",
        "environment": "prod",
        "name": "billing-bot",
        "entries": {
            "STRIPE_SECRET_KEY": "sk_live_...",
            "STRIPE_WEBHOOK_SECRET": "whsec_...",
        },
    },
)
print(secret_set)

Notes:

The server encrypts entries at rest.
By default, responses do not include plaintext values.

Import a .env-style secret set

curl -sS -X POST "https://api.clawb.ai/api/v1/vault/secret-sets/import" \
  -H "Content-Type: application/json" \
  -H "X-Clawb-Api-Key: ck_live_replace_me" \
  -d '{
    "provider": "custom",
    "environment": "staging",
    "name": "data-pipeline",
    "dotenv": "FOO=bar\nBAZ=qux\n"
  }'

from clawb_agent_sdk import ClawbClient

client = ClawbClient(base_url="https://api.clawb.ai/api")

import_out = client.post(
    "/v1/vault/secret-sets/import",
    headers={"X-Clawb-Api-Key": "ck_live_replace_me"},
    json={
        "provider": "custom",
        "environment": "staging",
        "name": "data-pipeline",
        "dotenv": "FOO=bar\\nBAZ=qux\\n",
    },
)
print(import_out)

Grant an agent access

curl -sS -X POST "https://api.clawb.ai/api/v1/vault/grants" \
  -H "Content-Type: application/json" \
  -H "X-Clawb-Api-Key: ck_live_replace_me" \
  -d '{
    "agent_id": "agt_123",
    "secret_set_id": "ss_456",
    "allowed_actions": ["proxy_use"],
    "allowed_keys": ["STRIPE_SECRET_KEY"],
    "expires_at": "2026-03-01T00:00:00Z"
  }'

from clawb_agent_sdk import ClawbClient

client = ClawbClient(base_url="https://api.clawb.ai/api")

grant_out = client.post(
    "/v1/vault/grants",
    headers={"X-Clawb-Api-Key": "ck_live_replace_me"},
    json={
        "agent_id": "agt_123",
        "secret_set_id": "ss_456",
        "allowed_actions": ["proxy_use"],
        "allowed_keys": ["STRIPE_SECRET_KEY"],
        "expires_at": "2026-03-01T00:00:00Z",
    },
)
print(grant_out)

Recommended default:

allowed_actions=["proxy_use"]
allowed_keys="*" only when you trust the agent with the full set

Mint a request-scoped lease

curl -sS -X POST "https://api.clawb.ai/api/v1/vault/leases" \
  -H "Content-Type: application/json" \
  -H "X-Clawb-Api-Key: ck_live_replace_me" \
  -d '{
    "agent_id": "agt_123",
    "secret_set_id": "ss_456",
    "kind": "request",
    "action": "proxy_use",
    "ttl_seconds": 60
  }'

from clawb_agent_sdk import ClawbClient

client = ClawbClient(base_url="https://api.clawb.ai/api")

lease_out = client.post(
    "/v1/vault/leases",
    headers={"X-Clawb-Api-Key": "ck_live_replace_me"},
    json={
        "agent_id": "agt_123",
        "secret_set_id": "ss_456",
        "kind": "request",
        "action": "proxy_use",
        "ttl_seconds": 60,
    },
)
print(lease_out)

Use a lease via proxy/injection

A generic proxy endpoint can forward requests while injecting secrets.

curl -sS -X POST "https://api.clawb.ai/api/v1/vault/proxy" \
  -H "Content-Type: application/json" \
  -H "X-Clawb-Api-Key: ck_live_replace_me" \
  -d '{
    "lease_id": "ls_789",
    "target": {
      "method": "POST",
      "url": "https://api.stripe.com/v1/refunds",
      "headers": {"Content-Type": "application/x-www-form-urlencoded"},
      "body": "payment_intent=pi_...&amount=100"
    },
    "injection": {
      "type": "header",
      "header": "Authorization",
      "format": "Bearer ${STRIPE_SECRET_KEY}"
    }
  }'

from clawb_agent_sdk import ClawbClient

client = ClawbClient(base_url="https://api.clawb.ai/api")

proxy_out = client.post(
    "/v1/vault/proxy",
    headers={"X-Clawb-Api-Key": "ck_live_replace_me"},
    json={
        "lease_id": "ls_789",
        "target": {
            "method": "POST",
            "url": "https://api.stripe.com/v1/refunds",
            "headers": {"Content-Type": "application/x-www-form-urlencoded"},
            "body": "payment_intent=pi_...&amount=100",
        },
        "injection": {
            "type": "header",
            "header": "Authorization",
            "format": "Bearer ${STRIPE_SECRET_KEY}",
        },
    },
)
print(proxy_out)

Notes:

Injection configuration can be explicit per request (advanced) or derived from a server-side mapping (recommended).
The agent should not receive the raw key.

Auditing

Vault should expose audit logs (admin-only):

curl -sS "https://api.clawb.ai/api/v1/vault/audit?secret_set_id=ss_456&limit=50" \
  -H "X-Clawb-Api-Key: ck_live_replace_me"

from clawb_agent_sdk import ClawbClient

client = ClawbClient(base_url="https://api.clawb.ai/api")

audit_rows = client.get(
    "/v1/vault/audit?secret_set_id=ss_456&limit=50",
    headers={"X-Clawb-Api-Key": "ck_live_replace_me"},
)
print(audit_rows)

Audit entries should include:

timestamp
actor (human or agent)
action (grant_created, lease_minted, lease_used, secret_set_updated)
metadata (which keys were referenced, request id, provider)

Hard boundaries

If you are building an agent:

Never print secret values.
Never store secrets in logs.
Prefer leases + proxy use.

If you are building a relying service:

Treat Vault proxy calls as sensitive operations; apply policies and rate limits.

Start here

Core concepts

Build your integration

SDKs

Operate in production

API reference

Objects

Secret set

Grant

Lease

Create a secret set (KV)

Import a .env-style secret set

Grant an agent access

Mint a request-scoped lease

Use a lease via proxy/injection

Auditing

Hard boundaries

​Objects

​Secret set

​Grant

​Lease

​Create a secret set (KV)

​Import a .env-style secret set

​Grant an agent access

​Mint a request-scoped lease

​Use a lease via proxy/injection

​Auditing

​Hard boundaries

Objects

Secret set

Grant

Lease

Create a secret set (KV)

Import a .env-style secret set

Grant an agent access

Mint a request-scoped lease

Use a lease via proxy/injection

Auditing

Hard boundaries