@1claw/openapi-spec 0.61.29 → 0.61.34

package/openapi.json

@@ -2,7 +2,7 @@
   "openapi": "3.1.0",
   "info": {
     "title": "1Claw API",
-    "version": "0.61.29",
+    "version": "0.61.34",
     "description": "Secure secret management for AI agents. Provides vaults, secrets,\npolicy-based access control, agent identity, Intents API,\nsharing, billing, and audit logging. Automations (workflow_spec,\nwebhook tokens, event triggers, Assist), cloud runtimes with\ninteractive shell sessions, agent memory, and discovery.\n\n## Domains\n\n`api.1claw.co` is canonical: it is the OIDC issuer, the `aud` the API\nmints, and the first entry in `servers` — a generated client takes its\nbase URL from there, and the previous ordering pointed every SDK at the\ndomain the issuer had already left. `api.1claw.xyz` still answers and is\nstill accepted on token validation, because tokens minted before the\nmove carry it; it is never minted now.\n\nOne deliberate exception: the Shroud attestation identity token is\nrequested from GCP with `audience: https://api.1claw.xyz`, so\n`/v1/shroud/attestation` reports that as its `expected_audience`. That\nis accurate rather than stale — the audience is a verification contract\nwith anyone already checking the token, and moving it is a breaking\nchange for them, not a rename.\n\nAll endpoints require JWT Bearer authentication unless marked with\n`security: []`.\n",
     "contact": {
       "email": "ops@1claw.co"
@@ -277,7 +277,7 @@
           "Authentication"
         ],
         "summary": "Exchange agent credentials for JWT",
-        "description": "Returns a short-lived EdDSA-signed JWT (`access_token`). Standard claims include `sub`\n(`agent:<uuid>`), `org`, `scopes`, `vault_ids`, optional `intents_api_enabled`, optional\n`shroud_enabled`, optional `llm_token_billing` / `stripe_customer_id` when org LLM billing is on.\n\nWhen **`shroud_enabled`** is true, the JWT payload may include **`shroud_config`**: a JSON object\nmirroring the agent row in Vault (same shape as `ShroudConfig` on `GET /v1/agents/{id}`).\n**Shroud** (TEE proxy) decodes this on each LLM request and runs **PolicyEngine** after the\nglobal inspection pipeline so per-agent limits and threat **block** actions apply without a\nseparate policy fetch. Re-exchange the agent token after changing `shroud_config` so the JWT\nis fresh.\n\nUser JWTs from password, API key, or device flow do **not** include `shroud_config`.\n",
+        "description": "Returns a short-lived EdDSA-signed JWT (`access_token`). Standard claims include `sub`\n(`agent:<uuid>`), `org`, `scopes`, `vault_ids`, optional `intents_api_enabled`, optional\n`shroud_enabled`, optional `llm_token_billing` / `stripe_customer_id` when org LLM billing is on.\n\nWhen **`shroud_enabled`** is true, the JWT payload may include **`shroud_config`**: a JSON object\nmirroring the agent row in Vault (same shape as `ShroudConfig` on `GET /v1/agents/{id}`).\n**Shroud** (TEE proxy) decodes this on each LLM request and runs **PolicyEngine** after the\nglobal inspection pipeline so per-agent limits and threat **block** actions apply without a\nseparate policy fetch. Re-exchange the agent token after changing `shroud_config` so the JWT\nis fresh.\n\nUser JWTs from password, API key, or device flow do **not** include `shroud_config`.\n\n**Router keys.** An `sk-shroud-v1-…` key (minted at\n`POST /v1/agents/{agent_id}/router-keys`) is exchanged key-only — send `api_key`\nalone, no `agent_id`. The token carries a `router_key` claim\n(`{id, max_concurrent_streams?, spend_cap_micro_usd?}`), lives at most **60 s**\n(revocation SLA), and is only issued for Shroud-enabled agents. Revoked keys get 401.\n",
         "operationId": "agentToken",
         "security": [],
         "requestBody": {
@@ -17221,6 +17221,75 @@
         }
       }
     },
+    "/v1/x402/topup": {
+      "post": {
+        "tags": [
+          "Billing"
+        ],
+        "summary": "x402 ledger top-up (agent door)",
+        "description": "The wallet rail for Shroud (Shroud AI plan). Without `X-PAYMENT` the response is a\n**402** quote (`x402Version`, `accepts[]` with `payTo`, `maxAmountRequired`, `resource`)\nfor `amount_usd` (default $1) of USDC on Base. With a signed EIP-3009 `X-PAYMENT`\nthe facilitator verifies it, the proof is claimed once, the payer wallet's org\nledger is credited in micro-USD, and the facilitator settles.\n\n**Payment is the account.** An unknown wallet's first settled top-up provisions a\nshadow org, one Shroud-enabled agent and one `sk-shroud-v1` router key keyed on the\nwallet (returned once as `router_key`), after screening the wallet against the OFAC\nSDN list (fails closed when the list is missing or stale) and the caller's region\nagainst the custody geofence. Same wallet = same org on every later top-up. The\nresponse always carries a ≤60 s `access_token` for the wallet's agent so the\ngateway can serve the paid request immediately. The Shroud gateway drives this for\n`Authorization: Bearer x402` requests and relays the quote or the result.\n",
+        "operationId": "x402Topup",
+        "security": [],
+        "parameters": [
+          {
+            "name": "X-PAYMENT",
+            "in": "header",
+            "required": false,
+            "schema": {
+              "type": "string"
+            },
+            "description": "Base64 x402 payment payload (EIP-3009 USDC authorization on Base)"
+          }
+        ],
+        "requestBody": {
+          "required": false,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "additionalProperties": false,
+                "properties": {
+                  "amount_usd": {
+                    "type": "integer",
+                    "minimum": 1,
+                    "maximum": 100,
+                    "description": "Whole dollars to add to the ledger (default 1)"
+                  }
+                }
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Credited",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/X402TopupResponse"
+                }
+              }
+            }
+          },
+          "402": {
+            "description": "Payment required — the quote to sign, or why the payment was refused",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/PaymentRequirement"
+                }
+              }
+            }
+          },
+          "403": {
+            "description": "The wallet is sanctioned or the region is fenced; no account is opened"
+          },
+          "503": {
+            "description": "The sanctions list is unavailable (fails closed)"
+          }
+        }
+      }
+    },
     "/v1/oauth/token": {
       "post": {
         "tags": [
@@ -23741,6 +23810,260 @@
         }
       }
     },
+    "/v1/agents/{agent_id}/router-keys": {
+      "post": {
+        "tags": [
+          "Agents"
+        ],
+        "summary": "Mint a router key (sk-shroud-v1)",
+        "description": "Creates an `sk-shroud-v1-<32>` static Bearer for the Shroud gateway, mapped to this\nagent. A stock OpenAI or Anthropic SDK sends it as `Authorization: Bearer …` with\n`base_url` set to the gateway; the gateway exchanges it key-only for the agent's\ntoken. The plaintext key is returned **once**. Up to 20 live keys per agent.\nHuman users only; the agent must have `shroud_enabled: true`.\n",
+        "operationId": "createRouterKey",
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/AgentId"
+          }
+        ],
+        "requestBody": {
+          "required": false,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/CreateRouterKeyRequest"
+              }
+            }
+          }
+        },
+        "responses": {
+          "201": {
+            "description": "Router key created (plaintext returned once)",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/RouterKeyCreated"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        }
+      },
+      "get": {
+        "tags": [
+          "Agents"
+        ],
+        "summary": "List router keys",
+        "description": "Every router key of the agent, live and revoked, without secrets.",
+        "operationId": "listRouterKeys",
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/AgentId"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Router keys",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "required": [
+                    "keys"
+                  ],
+                  "properties": {
+                    "keys": {
+                      "type": "array",
+                      "items": {
+                        "$ref": "#/components/schemas/RouterKey"
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        }
+      }
+    },
+    "/v1/agents/{agent_id}/router-keys/{key_id}": {
+      "delete": {
+        "tags": [
+          "Agents"
+        ],
+        "summary": "Revoke a router key",
+        "description": "Revokes the key. The gateway stops accepting it within 60 s (router-key tokens\nlive at most that long and the gateway re-exchanges on expiry). Idempotent.\nHuman users only.\n",
+        "operationId": "revokeRouterKey",
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/AgentId"
+          },
+          {
+            "name": "key_id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "format": "uuid"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Revoked",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/RouterKey"
+                }
+              }
+            }
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        }
+      }
+    },
+    "/v1/agents/{agent_id}/tool-bindings": {
+      "post": {
+        "tags": [
+          "Agents"
+        ],
+        "summary": "Create a secret → tool binding (rehydration policy)",
+        "description": "Authorises the enclave to rehydrate the `⟦sk:…⟧` placeholder for `secret_path`\ninto `tool_name` at `arg_path` — and only when the call's destination host is one\nof `destination_hosts`. Redaction replaces vault secrets in prompts with\ndeterministic placeholders the model can place but never read; a placeholder is\nsubstituted back only inside an authorised tool-call argument, at the moment the\nenclave performs the call (`execution_mode: \"tee\"`). No binding, wrong argument,\nwrong host, bad checksum or an unknown tag is a 403 at execution time. Human users\nonly; up to 200 per agent.\n",
+        "operationId": "createToolBinding",
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/AgentId"
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/CreateToolBindingRequest"
+              }
+            }
+          }
+        },
+        "responses": {
+          "201": {
+            "description": "Created",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/SecretToolBinding"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          },
+          "409": {
+            "description": "A binding for this secret, tool and argument already exists"
+          }
+        }
+      },
+      "get": {
+        "tags": [
+          "Agents"
+        ],
+        "summary": "List secret → tool bindings",
+        "operationId": "listToolBindings",
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/AgentId"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Bindings",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "required": [
+                    "bindings"
+                  ],
+                  "properties": {
+                    "bindings": {
+                      "type": "array",
+                      "items": {
+                        "$ref": "#/components/schemas/SecretToolBinding"
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        }
+      }
+    },
+    "/v1/agents/{agent_id}/tool-bindings/{binding_id}": {
+      "delete": {
+        "tags": [
+          "Agents"
+        ],
+        "summary": "Delete a secret → tool binding",
+        "operationId": "deleteToolBinding",
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/AgentId"
+          },
+          {
+            "name": "binding_id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "format": "uuid"
+            }
+          }
+        ],
+        "responses": {
+          "204": {
+            "description": "Deleted"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        }
+      }
+    },
     "/v1/agents/{agent_id}/oauth/connections": {
       "get": {
         "tags": [
@@ -33768,6 +34091,26 @@
             "minimum": 0,
             "maximum": 365,
             "description": "Number of days to retain flagged request bodies for replay/investigation"
+          },
+          "streaming_inspection_mode": {
+            "type": "string",
+            "enum": [
+              "rolling",
+              "holdback"
+            ],
+            "description": "How streamed LLM responses are inspected before release. `rolling` (default) releases text behind a tail buffer at least as long as the org's longest vault secret (capped at 256 bytes; longer secrets are matched by prefix); `holdback` buffers `streaming_holdback_chars` for full parity with buffered inspection. Tool-call deltas are always held until the call is complete."
+          },
+          "streaming_holdback_chars": {
+            "type": "integer",
+            "minimum": 64,
+            "maximum": 65536,
+            "description": "Characters held back per stream in holdback mode (default 512)"
+          },
+          "max_concurrent_streams": {
+            "type": "integer",
+            "minimum": 1,
+            "maximum": 1000,
+            "description": "Open streaming responses allowed per agent key (default 20; 429 with Retry-After beyond it)"
           }
         }
       },
@@ -35940,7 +36283,13 @@
             "type": "string"
           },
           "credit_balance_cents": {
-            "type": "integer"
+            "type": "integer",
+            "description": "Derived (rounded down); the ledger unit is micro-USD"
+          },
+          "credit_balance_micro_usd": {
+            "type": "integer",
+            "format": "int64",
+            "description": "The ledger value. One inspected Shroud request costs 5,000 micro-USD ($0.005)."
           },
           "credit_balance_usd": {
             "type": "string"
@@ -36163,10 +36512,17 @@
         "type": "object",
         "properties": {
           "balance_cents": {
-            "type": "integer"
+            "type": "integer",
+            "description": "Derived (rounded down); the ledger unit is micro-USD"
+          },
+          "balance_micro_usd": {
+            "type": "integer",
+            "format": "int64",
+            "description": "The ledger value (1 = $0.000001)"
           },
           "balance_usd": {
-            "type": "string"
+            "type": "string",
+            "description": "Dollars at the ledger's precision (e.g. \"4.995\"), never fewer than two decimals"
           },
           "expiring_within_90_days": {
             "type": "object",
@@ -39788,6 +40144,245 @@
           }
         }
       },
+      "CreateRouterKeyRequest": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "name": {
+            "type": "string",
+            "maxLength": 64,
+            "description": "Shown in lists; defaults to `default`"
+          },
+          "max_concurrent_streams": {
+            "type": "integer",
+            "minimum": 1,
+            "maximum": 1000,
+            "description": "Open streaming responses this key may hold at once (gateway default 20)"
+          },
+          "spend_cap_usd": {
+            "type": "number",
+            "minimum": 0,
+            "description": "Optional spend cap in USD, metered by the gateway"
+          }
+        }
+      },
+      "RouterKey": {
+        "type": "object",
+        "required": [
+          "id",
+          "agent_id",
+          "name",
+          "key_prefix",
+          "created_at"
+        ],
+        "properties": {
+          "id": {
+            "type": "string",
+            "format": "uuid"
+          },
+          "agent_id": {
+            "type": "string",
+            "format": "uuid"
+          },
+          "name": {
+            "type": "string"
+          },
+          "key_prefix": {
+            "type": "string",
+            "description": "First 20 characters (`sk-shroud-v1-` + 7) — enough to recognise, not to use"
+          },
+          "max_concurrent_streams": {
+            "type": "integer",
+            "nullable": true
+          },
+          "spend_cap_usd": {
+            "type": "number",
+            "nullable": true
+          },
+          "created_at": {
+            "type": "string",
+            "format": "date-time"
+          },
+          "last_used_at": {
+            "type": "string",
+            "format": "date-time",
+            "nullable": true
+          },
+          "revoked_at": {
+            "type": "string",
+            "format": "date-time",
+            "nullable": true
+          }
+        }
+      },
+      "RouterKeyCreated": {
+        "allOf": [
+          {
+            "$ref": "#/components/schemas/RouterKey"
+          },
+          {
+            "type": "object",
+            "required": [
+              "router_key",
+              "base_url"
+            ],
+            "properties": {
+              "router_key": {
+                "type": "string",
+                "description": "The plaintext `sk-shroud-v1-…` key. Returned once.",
+                "example": "sk-shroud-v1-Q2c5o0yQ3bHkT9m1vXz8Lw7nRp4aEf6u"
+              },
+              "base_url": {
+                "type": "string",
+                "description": "The Shroud gateway to point the SDK at",
+                "example": "https://shroud.1claw.co"
+              }
+            }
+          }
+        ]
+      },
+      "CreateToolBindingRequest": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "secret_path",
+          "tool_name",
+          "destination_hosts"
+        ],
+        "properties": {
+          "secret_path": {
+            "type": "string",
+            "description": "Vault path of the secret the placeholder stands for"
+          },
+          "tool_name": {
+            "type": "string",
+            "description": "Tool the binding applies to (`http_request`, `run_sql`, …) or `*`"
+          },
+          "arg_path": {
+            "type": "string",
+            "description": "JSON pointer into the tool's arguments (`/headers/Authorization`, `/body/*`) or `*` (default)"
+          },
+          "destination_hosts": {
+            "type": "array",
+            "minItems": 1,
+            "maxItems": 32,
+            "items": {
+              "type": "string"
+            },
+            "description": "Hosts the rehydrated call may reach (`api.stripe.com`, `*.googleapis.com`); required"
+          }
+        }
+      },
+      "SecretToolBinding": {
+        "type": "object",
+        "required": [
+          "id",
+          "org_id",
+          "agent_id",
+          "secret_path",
+          "tool_name",
+          "arg_path",
+          "destination_hosts",
+          "created_at"
+        ],
+        "properties": {
+          "id": {
+            "type": "string",
+            "format": "uuid"
+          },
+          "org_id": {
+            "type": "string",
+            "format": "uuid"
+          },
+          "agent_id": {
+            "type": "string",
+            "format": "uuid"
+          },
+          "secret_path": {
+            "type": "string"
+          },
+          "tool_name": {
+            "type": "string"
+          },
+          "arg_path": {
+            "type": "string"
+          },
+          "destination_hosts": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "created_by": {
+            "type": "string",
+            "format": "uuid",
+            "nullable": true
+          },
+          "created_at": {
+            "type": "string",
+            "format": "date-time"
+          }
+        }
+      },
+      "X402TopupResponse": {
+        "type": "object",
+        "required": [
+          "wallet",
+          "org_id",
+          "agent_id",
+          "credited_micro_usd",
+          "balance_micro_usd",
+          "balance_usd",
+          "access_token",
+          "expires_in",
+          "base_url",
+          "provisioned"
+        ],
+        "properties": {
+          "wallet": {
+            "type": "string",
+            "description": "Payer address (lower-case)"
+          },
+          "org_id": {
+            "type": "string",
+            "format": "uuid"
+          },
+          "agent_id": {
+            "type": "string",
+            "format": "uuid"
+          },
+          "credited_micro_usd": {
+            "type": "integer",
+            "format": "int64"
+          },
+          "balance_micro_usd": {
+            "type": "integer",
+            "format": "int64"
+          },
+          "balance_usd": {
+            "type": "string"
+          },
+          "router_key": {
+            "type": "string",
+            "description": "Present only on the top-up that provisioned the account (or re-minted a lost key). Shown once."
+          },
+          "access_token": {
+            "type": "string",
+            "description": "A ≤60 s agent token for the wallet's agent (carries the `router_key` claim)"
+          },
+          "expires_in": {
+            "type": "integer"
+          },
+          "base_url": {
+            "type": "string",
+            "description": "The Shroud gateway"
+          },
+          "provisioned": {
+            "type": "boolean",
+            "description": "True when this top-up created the account"
+          }
+        }
+      },
       "EventSubscription": {
         "type": "object",
         "required": [

package/openapi.yaml

@@ -2,7 +2,7 @@ openapi: 3.1.0
 
 info:
     title: 1Claw API
-    version: "0.61.29"
+    version: "0.61.34"
     description: |
         Secure secret management for AI agents. Provides vaults, secrets,
         policy-based access control, agent identity, Intents API,
@@ -198,6 +198,12 @@ paths:
                 is fresh.
 
                 User JWTs from password, API key, or device flow do **not** include `shroud_config`.
+
+                **Router keys.** An `sk-shroud-v1-…` key (minted at
+                `POST /v1/agents/{agent_id}/router-keys`) is exchanged key-only — send `api_key`
+                alone, no `agent_id`. The token carries a `router_key` claim
+                (`{id, max_concurrent_streams?, spend_cap_micro_usd?}`), lives at most **60 s**
+                (revocation SLA), and is only issued for Shroud-enabled agents. Revoked keys get 401.
             operationId: agentToken
             security: []
             requestBody:
@@ -10950,6 +10956,64 @@ paths:
                 "400":
                     description: Invalid request
 
+    /v1/x402/topup:
+        post:
+            tags: [Billing]
+            summary: x402 ledger top-up (agent door)
+            description: |
+                The wallet rail for Shroud (Shroud AI plan). Without `X-PAYMENT` the response is a
+                **402** quote (`x402Version`, `accepts[]` with `payTo`, `maxAmountRequired`, `resource`)
+                for `amount_usd` (default $1) of USDC on Base. With a signed EIP-3009 `X-PAYMENT`
+                the facilitator verifies it, the proof is claimed once, the payer wallet's org
+                ledger is credited in micro-USD, and the facilitator settles.
+
+                **Payment is the account.** An unknown wallet's first settled top-up provisions a
+                shadow org, one Shroud-enabled agent and one `sk-shroud-v1` router key keyed on the
+                wallet (returned once as `router_key`), after screening the wallet against the OFAC
+                SDN list (fails closed when the list is missing or stale) and the caller's region
+                against the custody geofence. Same wallet = same org on every later top-up. The
+                response always carries a ≤60 s `access_token` for the wallet's agent so the
+                gateway can serve the paid request immediately. The Shroud gateway drives this for
+                `Authorization: Bearer x402` requests and relays the quote or the result.
+            operationId: x402Topup
+            security: []
+            parameters:
+                - name: X-PAYMENT
+                  in: header
+                  required: false
+                  schema: { type: string }
+                  description: Base64 x402 payment payload (EIP-3009 USDC authorization on Base)
+            requestBody:
+                required: false
+                content:
+                    application/json:
+                        schema:
+                            type: object
+                            additionalProperties: false
+                            properties:
+                                amount_usd:
+                                    type: integer
+                                    minimum: 1
+                                    maximum: 100
+                                    description: Whole dollars to add to the ledger (default 1)
+            responses:
+                "200":
+                    description: Credited
+                    content:
+                        application/json:
+                            schema:
+                                $ref: "#/components/schemas/X402TopupResponse"
+                "402":
+                    description: Payment required — the quote to sign, or why the payment was refused
+                    content:
+                        application/json:
+                            schema:
+                                $ref: "#/components/schemas/PaymentRequirement"
+                "403":
+                    description: The wallet is sanctioned or the region is fenced; no account is opened
+                "503":
+                    description: The sanctions list is unavailable (fails closed)
+
     /v1/oauth/token:
         post:
             tags: [OAuth]
@@ -15180,6 +15244,170 @@ paths:
                 "404":
                     $ref: "#/components/responses/NotFound"
 
+    /v1/agents/{agent_id}/router-keys:
+        post:
+            tags: [Agents]
+            summary: Mint a router key (sk-shroud-v1)
+            description: |
+                Creates an `sk-shroud-v1-<32>` static Bearer for the Shroud gateway, mapped to this
+                agent. A stock OpenAI or Anthropic SDK sends it as `Authorization: Bearer …` with
+                `base_url` set to the gateway; the gateway exchanges it key-only for the agent's
+                token. The plaintext key is returned **once**. Up to 20 live keys per agent.
+                Human users only; the agent must have `shroud_enabled: true`.
+            operationId: createRouterKey
+            parameters:
+                - $ref: "#/components/parameters/AgentId"
+            requestBody:
+                required: false
+                content:
+                    application/json:
+                        schema:
+                            $ref: "#/components/schemas/CreateRouterKeyRequest"
+            responses:
+                "201":
+                    description: Router key created (plaintext returned once)
+                    content:
+                        application/json:
+                            schema:
+                                $ref: "#/components/schemas/RouterKeyCreated"
+                "400":
+                    $ref: "#/components/responses/BadRequest"
+                "403":
+                    $ref: "#/components/responses/Forbidden"
+                "404":
+                    $ref: "#/components/responses/NotFound"
+        get:
+            tags: [Agents]
+            summary: List router keys
+            description: Every router key of the agent, live and revoked, without secrets.
+            operationId: listRouterKeys
+            parameters:
+                - $ref: "#/components/parameters/AgentId"
+            responses:
+                "200":
+                    description: Router keys
+                    content:
+                        application/json:
+                            schema:
+                                type: object
+                                required: [keys]
+                                properties:
+                                    keys:
+                                        type: array
+                                        items:
+                                            $ref: "#/components/schemas/RouterKey"
+                "403":
+                    $ref: "#/components/responses/Forbidden"
+                "404":
+                    $ref: "#/components/responses/NotFound"
+
+    /v1/agents/{agent_id}/router-keys/{key_id}:
+        delete:
+            tags: [Agents]
+            summary: Revoke a router key
+            description: |
+                Revokes the key. The gateway stops accepting it within 60 s (router-key tokens
+                live at most that long and the gateway re-exchanges on expiry). Idempotent.
+                Human users only.
+            operationId: revokeRouterKey
+            parameters:
+                - $ref: "#/components/parameters/AgentId"
+                - name: key_id
+                  in: path
+                  required: true
+                  schema: { type: string, format: uuid }
+            responses:
+                "200":
+                    description: Revoked
+                    content:
+                        application/json:
+                            schema:
+                                $ref: "#/components/schemas/RouterKey"
+                "403":
+                    $ref: "#/components/responses/Forbidden"
+                "404":
+                    $ref: "#/components/responses/NotFound"
+
+    /v1/agents/{agent_id}/tool-bindings:
+        post:
+            tags: [Agents]
+            summary: Create a secret → tool binding (rehydration policy)
+            description: |
+                Authorises the enclave to rehydrate the `⟦sk:…⟧` placeholder for `secret_path`
+                into `tool_name` at `arg_path` — and only when the call's destination host is one
+                of `destination_hosts`. Redaction replaces vault secrets in prompts with
+                deterministic placeholders the model can place but never read; a placeholder is
+                substituted back only inside an authorised tool-call argument, at the moment the
+                enclave performs the call (`execution_mode: "tee"`). No binding, wrong argument,
+                wrong host, bad checksum or an unknown tag is a 403 at execution time. Human users
+                only; up to 200 per agent.
+            operationId: createToolBinding
+            parameters:
+                - $ref: "#/components/parameters/AgentId"
+            requestBody:
+                required: true
+                content:
+                    application/json:
+                        schema:
+                            $ref: "#/components/schemas/CreateToolBindingRequest"
+            responses:
+                "201":
+                    description: Created
+                    content:
+                        application/json:
+                            schema:
+                                $ref: "#/components/schemas/SecretToolBinding"
+                "400":
+                    $ref: "#/components/responses/BadRequest"
+                "403":
+                    $ref: "#/components/responses/Forbidden"
+                "404":
+                    $ref: "#/components/responses/NotFound"
+                "409":
+                    description: A binding for this secret, tool and argument already exists
+        get:
+            tags: [Agents]
+            summary: List secret → tool bindings
+            operationId: listToolBindings
+            parameters:
+                - $ref: "#/components/parameters/AgentId"
+            responses:
+                "200":
+                    description: Bindings
+                    content:
+                        application/json:
+                            schema:
+                                type: object
+                                required: [bindings]
+                                properties:
+                                    bindings:
+                                        type: array
+                                        items:
+                                            $ref: "#/components/schemas/SecretToolBinding"
+                "403":
+                    $ref: "#/components/responses/Forbidden"
+                "404":
+                    $ref: "#/components/responses/NotFound"
+
+    /v1/agents/{agent_id}/tool-bindings/{binding_id}:
+        delete:
+            tags: [Agents]
+            summary: Delete a secret → tool binding
+            operationId: deleteToolBinding
+            parameters:
+                - $ref: "#/components/parameters/AgentId"
+                - name: binding_id
+                  in: path
+                  required: true
+                  schema: { type: string, format: uuid }
+            responses:
+                "204":
+                    description: Deleted
+                "403":
+                    $ref: "#/components/responses/Forbidden"
+                "404":
+                    $ref: "#/components/responses/NotFound"
+
     /v1/agents/{agent_id}/oauth/connections:
         get:
             tags: [OAuth Connect]
@@ -21757,6 +21985,25 @@ components:
                     minimum: 0
                     maximum: 365
                     description: Number of days to retain flagged request bodies for replay/investigation
+                streaming_inspection_mode:
+                    type: string
+                    enum: [rolling, holdback]
+                    description: >-
+                        How streamed LLM responses are inspected before release. `rolling` (default)
+                        releases text behind a tail buffer at least as long as the org's longest vault
+                        secret (capped at 256 bytes; longer secrets are matched by prefix); `holdback`
+                        buffers `streaming_holdback_chars` for full parity with buffered inspection.
+                        Tool-call deltas are always held until the call is complete.
+                streaming_holdback_chars:
+                    type: integer
+                    minimum: 64
+                    maximum: 65536
+                    description: Characters held back per stream in holdback mode (default 512)
+                max_concurrent_streams:
+                    type: integer
+                    minimum: 1
+                    maximum: 1000
+                    description: Open streaming responses allowed per agent key (default 20; 429 with Retry-After beyond it)
 
         UnicodeNormalizationConfig:
             type: object
@@ -23321,6 +23568,11 @@ components:
                     type: string
                 credit_balance_cents:
                     type: integer
+                    description: Derived (rounded down); the ledger unit is micro-USD
+                credit_balance_micro_usd:
+                    type: integer
+                    format: int64
+                    description: The ledger value. One inspected Shroud request costs 5,000 micro-USD ($0.005).
                 credit_balance_usd:
                     type: string
                 overage_method:
@@ -23477,8 +23729,14 @@ components:
             properties:
                 balance_cents:
                     type: integer
+                    description: Derived (rounded down); the ledger unit is micro-USD
+                balance_micro_usd:
+                    type: integer
+                    format: int64
+                    description: The ledger value (1 = $0.000001)
                 balance_usd:
                     type: string
+                    description: Dollars at the ledger's precision (e.g. "4.995"), never fewer than two decimals
                 expiring_within_90_days:
                     type: object
                     properties:
@@ -25824,6 +26082,112 @@ components:
                     description: Pointers within one item whose values together identify it.
                 min_interval_secs: { type: integer, example: 60 }
 
+        CreateRouterKeyRequest:
+            type: object
+            additionalProperties: false
+            properties:
+                name:
+                    type: string
+                    maxLength: 64
+                    description: Shown in lists; defaults to `default`
+                max_concurrent_streams:
+                    type: integer
+                    minimum: 1
+                    maximum: 1000
+                    description: Open streaming responses this key may hold at once (gateway default 20)
+                spend_cap_usd:
+                    type: number
+                    minimum: 0
+                    description: Optional spend cap in USD, metered by the gateway
+
+        RouterKey:
+            type: object
+            required: [id, agent_id, name, key_prefix, created_at]
+            properties:
+                id: { type: string, format: uuid }
+                agent_id: { type: string, format: uuid }
+                name: { type: string }
+                key_prefix:
+                    type: string
+                    description: First 20 characters (`sk-shroud-v1-` + 7) — enough to recognise, not to use
+                max_concurrent_streams: { type: integer, nullable: true }
+                spend_cap_usd: { type: number, nullable: true }
+                created_at: { type: string, format: date-time }
+                last_used_at: { type: string, format: date-time, nullable: true }
+                revoked_at: { type: string, format: date-time, nullable: true }
+
+        RouterKeyCreated:
+            allOf:
+                - $ref: "#/components/schemas/RouterKey"
+                - type: object
+                  required: [router_key, base_url]
+                  properties:
+                      router_key:
+                          type: string
+                          description: The plaintext `sk-shroud-v1-…` key. Returned once.
+                          example: sk-shroud-v1-Q2c5o0yQ3bHkT9m1vXz8Lw7nRp4aEf6u
+                      base_url:
+                          type: string
+                          description: The Shroud gateway to point the SDK at
+                          example: https://shroud.1claw.co
+
+        CreateToolBindingRequest:
+            type: object
+            additionalProperties: false
+            required: [secret_path, tool_name, destination_hosts]
+            properties:
+                secret_path:
+                    type: string
+                    description: Vault path of the secret the placeholder stands for
+                tool_name:
+                    type: string
+                    description: Tool the binding applies to (`http_request`, `run_sql`, …) or `*`
+                arg_path:
+                    type: string
+                    description: JSON pointer into the tool's arguments (`/headers/Authorization`, `/body/*`) or `*` (default)
+                destination_hosts:
+                    type: array
+                    minItems: 1
+                    maxItems: 32
+                    items: { type: string }
+                    description: Hosts the rehydrated call may reach (`api.stripe.com`, `*.googleapis.com`); required
+
+        SecretToolBinding:
+            type: object
+            required: [id, org_id, agent_id, secret_path, tool_name, arg_path, destination_hosts, created_at]
+            properties:
+                id: { type: string, format: uuid }
+                org_id: { type: string, format: uuid }
+                agent_id: { type: string, format: uuid }
+                secret_path: { type: string }
+                tool_name: { type: string }
+                arg_path: { type: string }
+                destination_hosts:
+                    type: array
+                    items: { type: string }
+                created_by: { type: string, format: uuid, nullable: true }
+                created_at: { type: string, format: date-time }
+
+        X402TopupResponse:
+            type: object
+            required: [wallet, org_id, agent_id, credited_micro_usd, balance_micro_usd, balance_usd, access_token, expires_in, base_url, provisioned]
+            properties:
+                wallet: { type: string, description: Payer address (lower-case) }
+                org_id: { type: string, format: uuid }
+                agent_id: { type: string, format: uuid }
+                credited_micro_usd: { type: integer, format: int64 }
+                balance_micro_usd: { type: integer, format: int64 }
+                balance_usd: { type: string }
+                router_key:
+                    type: string
+                    description: Present only on the top-up that provisioned the account (or re-minted a lost key). Shown once.
+                access_token:
+                    type: string
+                    description: A ≤60 s agent token for the wallet's agent (carries the `router_key` claim)
+                expires_in: { type: integer }
+                base_url: { type: string, description: The Shroud gateway }
+                provisioned: { type: boolean, description: True when this top-up created the account }
+
         EventSubscription:
             type: object
             required: [id, agent_id, binding_id, event_type, interval_secs, is_active, primed, next_poll_at, consecutive_errors, events_emitted, created_at]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@1claw/openapi-spec",
-  "version": "0.61.29",
+  "version": "0.61.34",
   "description": "OpenAPI 3.1.0 specification for the 1Claw Vault API \u2014 generate clients in any language",
   "license": "MIT",
   "repository": {