> ## Documentation Index
> Fetch the complete documentation index at: https://docs.clawb.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 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)

<CodeGroup>
  ```bash curl theme={null}
  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_..."
      }
    }'
  ```

  ```python Python SDK theme={null}
  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)
  ```
</CodeGroup>

Notes:

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

***

## Import a .env-style secret set

<CodeGroup>
  ```bash curl theme={null}
  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"
    }'
  ```

  ```python Python SDK theme={null}
  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)
  ```
</CodeGroup>

***

## Grant an agent access

<CodeGroup>
  ```bash curl theme={null}
  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"
    }'
  ```

  ```python Python SDK theme={null}
  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)
  ```
</CodeGroup>

Recommended default:

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

***

## Mint a request-scoped lease

<CodeGroup>
  ```bash curl theme={null}
  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
    }'
  ```

  ```python Python SDK theme={null}
  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)
  ```
</CodeGroup>

***

## Use a lease via proxy/injection

A generic proxy endpoint can forward requests while injecting secrets.

<CodeGroup>
  ```bash curl theme={null}
  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}"
      }
    }'
  ```

  ```python Python SDK theme={null}
  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)
  ```
</CodeGroup>

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):

<CodeGroup>
  ```bash curl theme={null}
  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"
  ```

  ```python Python SDK theme={null}
  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)
  ```
</CodeGroup>

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.