@1claw/openapi-spec 0.31.0 → 0.32.1

package/README.md

@@ -40,7 +40,11 @@ openapi-generator generate \
 import spec from "@1claw/openapi-spec/openapi.json";
 ```
 
-## What's in the spec (v0.31.0 — API `info.version` 2.17.0)
+## What's in the spec (v0.32.0 — API `info.version` 2.18.0)
+
+### Bankr dynamic key vending (2.18)
+- **Bankr keys** — `POST /v1/agents/{id}/bankr-keys/lease`, `GET /v1/agents/{id}/bankr-keys`, `DELETE /v1/agents/{id}/bankr-keys/{lease_id}`. Partner key vending for scoped, TTL-bound `bk_usr_` wallet API keys.
+
 
 ### CDP parity & embedded wallet (2.16+)
 - **Deposit destinations** — `POST/GET/PATCH /v1/deposit-destinations`, `GET /v1/deposit-destinations/{id}`

package/openapi.json

@@ -2,7 +2,7 @@
   "openapi": "3.1.0",
   "info": {
     "title": "1Claw API",
-    "version": "2.17.0",
+    "version": "2.18.0",
     "description": "Secure secret management for AI agents. Provides vaults, secrets,\npolicy-based access control, agent identity, Intents API,\nsharing, billing, and audit logging.\n\nAll endpoints require JWT Bearer authentication unless marked with\n`security: []`.\n",
     "contact": {
       "email": "ops@1claw.xyz"
@@ -3687,6 +3687,109 @@
         }
       }
     },
+    "/v1/agents/{agent_id}/bankr-keys/lease": {
+      "post": {
+        "tags": [
+          "Bankr Keys"
+        ],
+        "summary": "Lease a short-lived Bankr wallet API key",
+        "description": "Provision a scoped, time-limited Bankr wallet API key for an agent.\n**Privileged, deny-by-default:** agent callers need an explicit access policy\non `agents/{agent_id}/bankr/*` in the `__agent-keys` vault (JWT scope\n`agents/{agent_id}/bankr/lease`). Agents may only lease for their own ID.\nThe `bk_usr_` key is **omitted** from the JSON response for agent JWTs —\nstored server-side for Shroud resolution. Human callers receive `api_key` once.\nRequires `BANKR_PARTNER_KEY` on Vault. Agent default TTL 15 min when omitted;\nhuman/org default 1 hour (`BANKR_DEFAULT_LEASE_TTL_SECS`). Recommend 5–15 min\nfor autonomous agents. Max TTL 24 hours. Max 5 concurrent leases per agent.\n",
+        "operationId": "leaseBankrKey",
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/AgentId"
+          }
+        ],
+        "requestBody": {
+          "required": false,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/LeaseBankrKeyRequest"
+              }
+            }
+          }
+        },
+        "responses": {
+          "201": {
+            "description": "Bankr key leased",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/LeaseBankrKeyResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          }
+        }
+      }
+    },
+    "/v1/agents/{agent_id}/bankr-keys": {
+      "get": {
+        "tags": [
+          "Bankr Keys"
+        ],
+        "summary": "List active Bankr key leases for an agent",
+        "operationId": "listBankrKeys",
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/AgentId"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Active leases (no secret values)",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/BankrKeyLeaseListResponse"
+                }
+              }
+            }
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        }
+      }
+    },
+    "/v1/agents/{agent_id}/bankr-keys/{lease_id}": {
+      "delete": {
+        "tags": [
+          "Bankr Keys"
+        ],
+        "summary": "Revoke an active Bankr key lease",
+        "operationId": "revokeBankrKey",
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/AgentId"
+          },
+          {
+            "name": "lease_id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "format": "uuid"
+            }
+          }
+        ],
+        "responses": {
+          "204": {
+            "description": "Lease revoked"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        }
+      }
+    },
     "/v1/agents/{agent_id}/sign": {
       "post": {
         "tags": [
@@ -8094,15 +8197,38 @@
           "Authentication"
         ],
         "summary": "Begin passkey transaction authorization",
+        "description": "Requires `tx_digest` — SHA-256 hex of canonical `chain|to|value_wei|data`\nfor the treasury send being authorized. The server recomputes this digest\non send and rejects passkey tokens that do not match.\n",
         "operationId": "passkeyTxAssertBegin",
         "security": [
           {
             "BearerAuth": []
           }
         ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "required": [
+                  "tx_digest"
+                ],
+                "properties": {
+                  "tx_digest": {
+                    "type": "string",
+                    "description": "64-char hex SHA-256 of canonical send params"
+                  }
+                }
+              }
+            }
+          }
+        },
         "responses": {
           "200": {
             "description": "WebAuthn challenge"
+          },
+          "400": {
+            "description": "Missing or invalid tx_digest"
           }
         }
       }
@@ -10764,6 +10890,98 @@
           }
         }
       },
+      "LeaseBankrKeyRequest": {
+        "type": "object",
+        "properties": {
+          "wallet_id": {
+            "type": "string",
+            "description": "Bankr wallet ID (wlt_...). Uses org default if omitted."
+          },
+          "ttl_seconds": {
+            "type": "integer",
+            "description": "Lease TTL in seconds (default 3600, max 86400).",
+            "minimum": 60,
+            "maximum": 86400
+          },
+          "permissions": {
+            "$ref": "#/components/schemas/LeaseBankrPermissions"
+          }
+        }
+      },
+      "LeaseBankrPermissions": {
+        "type": "object",
+        "properties": {
+          "llm_gateway_enabled": {
+            "type": "boolean",
+            "default": true
+          },
+          "agent_api_enabled": {
+            "type": "boolean",
+            "default": false
+          },
+          "read_only": {
+            "type": "boolean",
+            "default": true
+          }
+        }
+      },
+      "LeaseBankrKeyResponse": {
+        "type": "object",
+        "properties": {
+          "lease_id": {
+            "type": "string",
+            "format": "uuid"
+          },
+          "api_key": {
+            "type": "string",
+            "description": "Ephemeral bk_usr_ key. Present for human callers only; omitted for agent JWTs."
+          },
+          "wallet_id": {
+            "type": "string"
+          },
+          "expires_at": {
+            "type": "string",
+            "format": "date-time"
+          }
+        }
+      },
+      "BankrKeyLeaseResponse": {
+        "type": "object",
+        "properties": {
+          "id": {
+            "type": "string",
+            "format": "uuid"
+          },
+          "wallet_id": {
+            "type": "string"
+          },
+          "bankr_key_id": {
+            "type": "string"
+          },
+          "permissions": {
+            "type": "object"
+          },
+          "expires_at": {
+            "type": "string",
+            "format": "date-time"
+          },
+          "created_at": {
+            "type": "string",
+            "format": "date-time"
+          }
+        }
+      },
+      "BankrKeyLeaseListResponse": {
+        "type": "object",
+        "properties": {
+          "leases": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/BankrKeyLeaseResponse"
+            }
+          }
+        }
+      },
       "SignIntentRequest": {
         "type": "object",
         "required": [

package/openapi.yaml

@@ -2,7 +2,7 @@ openapi: 3.1.0
 
 info:
     title: 1Claw API
-    version: 2.17.0
+    version: 2.18.0
     description: |
         Secure secret management for AI agents. Provides vaults, secrets,
         policy-based access control, agent identity, Intents API,
@@ -2413,6 +2413,81 @@ paths:
                 "404":
                     $ref: "#/components/responses/NotFound"
 
+    # ---------------------------------------------------------------------------
+    # Bankr Dynamic Key Vending
+    # ---------------------------------------------------------------------------
+
+    /v1/agents/{agent_id}/bankr-keys/lease:
+        post:
+            tags: [Bankr Keys]
+            summary: Lease a short-lived Bankr wallet API key
+            description: |
+                Provision a scoped, time-limited Bankr wallet API key for an agent.
+                **Privileged, deny-by-default:** agent callers need an explicit access policy
+                on `agents/{agent_id}/bankr/*` in the `__agent-keys` vault (JWT scope
+                `agents/{agent_id}/bankr/lease`). Agents may only lease for their own ID.
+                The `bk_usr_` key is **omitted** from the JSON response for agent JWTs —
+                stored server-side for Shroud resolution. Human callers receive `api_key` once.
+                Requires `BANKR_PARTNER_KEY` on Vault. Agent default TTL 15 min when omitted;
+                human/org default 1 hour (`BANKR_DEFAULT_LEASE_TTL_SECS`). Recommend 5–15 min
+                for autonomous agents. Max TTL 24 hours. Max 5 concurrent leases per agent.
+            operationId: leaseBankrKey
+            parameters:
+                - $ref: "#/components/parameters/AgentId"
+            requestBody:
+                required: false
+                content:
+                    application/json:
+                        schema:
+                            $ref: "#/components/schemas/LeaseBankrKeyRequest"
+            responses:
+                "201":
+                    description: Bankr key leased
+                    content:
+                        application/json:
+                            schema:
+                                $ref: "#/components/schemas/LeaseBankrKeyResponse"
+                "400":
+                    $ref: "#/components/responses/BadRequest"
+                "403":
+                    $ref: "#/components/responses/Forbidden"
+
+    /v1/agents/{agent_id}/bankr-keys:
+        get:
+            tags: [Bankr Keys]
+            summary: List active Bankr key leases for an agent
+            operationId: listBankrKeys
+            parameters:
+                - $ref: "#/components/parameters/AgentId"
+            responses:
+                "200":
+                    description: Active leases (no secret values)
+                    content:
+                        application/json:
+                            schema:
+                                $ref: "#/components/schemas/BankrKeyLeaseListResponse"
+                "404":
+                    $ref: "#/components/responses/NotFound"
+
+    /v1/agents/{agent_id}/bankr-keys/{lease_id}:
+        delete:
+            tags: [Bankr Keys]
+            summary: Revoke an active Bankr key lease
+            operationId: revokeBankrKey
+            parameters:
+                - $ref: "#/components/parameters/AgentId"
+                - name: lease_id
+                  in: path
+                  required: true
+                  schema:
+                      type: string
+                      format: uuid
+            responses:
+                "204":
+                    description: Lease revoked
+                "404":
+                    $ref: "#/components/responses/NotFound"
+
     # ---------------------------------------------------------------------------
     # Unified Signing Intent
     # ---------------------------------------------------------------------------
@@ -5173,12 +5248,29 @@ paths:
         post:
             tags: [Authentication]
             summary: Begin passkey transaction authorization
+            description: |
+                Requires `tx_digest` — SHA-256 hex of canonical `chain|to|value_wei|data`
+                for the treasury send being authorized. The server recomputes this digest
+                on send and rejects passkey tokens that do not match.
             operationId: passkeyTxAssertBegin
             security:
                 - BearerAuth: []
+            requestBody:
+                required: true
+                content:
+                    application/json:
+                        schema:
+                            type: object
+                            required: [tx_digest]
+                            properties:
+                                tx_digest:
+                                    type: string
+                                    description: 64-char hex SHA-256 of canonical send params
             responses:
                 "200":
                     description: WebAuthn challenge
+                "400":
+                    description: Missing or invalid tx_digest
 
     /v1/auth/passkeys/tx-assert/complete:
         post:
@@ -7041,6 +7133,76 @@ components:
                     items:
                         $ref: "#/components/schemas/SigningKeyResponse"
 
+        # Bankr Dynamic Key Vending
+        LeaseBankrKeyRequest:
+            type: object
+            properties:
+                wallet_id:
+                    type: string
+                    description: Bankr wallet ID (wlt_...). Uses org default if omitted.
+                ttl_seconds:
+                    type: integer
+                    description: Lease TTL in seconds (default 3600, max 86400).
+                    minimum: 60
+                    maximum: 86400
+                permissions:
+                    $ref: "#/components/schemas/LeaseBankrPermissions"
+
+        LeaseBankrPermissions:
+            type: object
+            properties:
+                llm_gateway_enabled:
+                    type: boolean
+                    default: true
+                agent_api_enabled:
+                    type: boolean
+                    default: false
+                read_only:
+                    type: boolean
+                    default: true
+
+        LeaseBankrKeyResponse:
+            type: object
+            properties:
+                lease_id:
+                    type: string
+                    format: uuid
+                api_key:
+                    type: string
+                    description: Ephemeral bk_usr_ key. Present for human callers only; omitted for agent JWTs.
+                wallet_id:
+                    type: string
+                expires_at:
+                    type: string
+                    format: date-time
+
+        BankrKeyLeaseResponse:
+            type: object
+            properties:
+                id:
+                    type: string
+                    format: uuid
+                wallet_id:
+                    type: string
+                bankr_key_id:
+                    type: string
+                permissions:
+                    type: object
+                expires_at:
+                    type: string
+                    format: date-time
+                created_at:
+                    type: string
+                    format: date-time
+
+        BankrKeyLeaseListResponse:
+            type: object
+            properties:
+                leases:
+                    type: array
+                    items:
+                        $ref: "#/components/schemas/BankrKeyLeaseResponse"
+
         # Unified Signing Intent
         SignIntentRequest:
             type: object

package/package.json

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