@1claw/openapi-spec 0.30.0 → 0.32.0

package/README.md

@@ -40,7 +40,20 @@ openapi-generator generate \
 import spec from "@1claw/openapi-spec/openapi.json";
 ```
 
-## What's in the spec (v0.28.0 — API `info.version` 2.15.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}`
+- **Internal accounts** — `POST/GET /v1/internal-accounts`, `POST /v1/internal-transfers` (supports `Idempotency-Key`), `GET /v1/internal-accounts/{id}/ledger`
+- **Fiat ramps** — `POST /v1/fiat/onramp/session`, `POST /v1/fiat/offramp/initiate`, `POST /v1/fiat/webhooks` (MoonPay signature required in production)
+- **Social login** — `POST /v1/auth/social-login` (Google/Apple ID tokens with audience validation; Discord authorization code + `oauth_redirect_uri`; no email auto-linking — 409 on conflict)
+- **Passkey tx auth** — `POST /v1/auth/passkeys/tx-assert/begin|complete` → `X-Passkey-Token` (+ optional `X-Passkey-Tx-Digest`) on treasury send
+
+### Core API (summary)
 
 - **OIDC Federation (1claw as IdP)** — `GET /.well-known/openid-configuration` (public discovery: issuer, jwks_uri, supported algs `["EdDSA","RS256"]`, supported grant types incl. token-exchange), `GET /.well-known/jwks.json` (public JWKS — every active EdDSA + RS256 key version, keyed by deterministic `kid`), `POST /v1/auth/federated-token` (RFC 8693 token exchange — accepts JSON or `application/x-www-form-urlencoded`; subject token is an agent JWT or `ocv_` API key; returns RS256 JWT scoped to `audience`). Agent fields: `federation_enabled`, `federation_audiences[]`, `federated_token_ttl_seconds`. Designed for Anthropic Workload Identity Federation, GCP STS, AWS STS, etc.
 - **Auth — agent JWT** — `POST /v1/auth/agent-token` documents optional JWT claim **`shroud_config`** when the agent has Shroud enabled (mirrors DB; consumed by Shroud PolicyEngine on LLM requests). Re-exchange after changing agent Shroud settings. Federation tokens use a separate KMS RSA-2048 key and are signed RS256.

package/openapi.json

@@ -2,7 +2,7 @@
   "openapi": "3.1.0",
   "info": {
     "title": "1Claw API",
-    "version": "2.16.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.\nRequires `BANKR_PARTNER_KEY` configured on the Vault service.\nDefault TTL 1 hour, max 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": [
@@ -8054,7 +8157,18 @@
                     ]
                   },
                   "id_token": {
-                    "type": "string"
+                    "type": "string",
+                    "description": "Google/Apple ID token, or Discord OAuth authorization code"
+                  },
+                  "oauth_redirect_uri": {
+                    "type": "string",
+                    "description": "Required for Discord — must match the redirect URI used in the OAuth flow"
+                  },
+                  "auto_provision_chains": {
+                    "type": "array",
+                    "items": {
+                      "type": "string"
+                    }
                   }
                 }
               }
@@ -8067,6 +8181,12 @@
           },
           "201": {
             "description": "New user created"
+          },
+          "401": {
+            "description": "Invalid or unverified token"
+          },
+          "409": {
+            "description": "Email already registered (no auto-linking)"
           }
         }
       }
@@ -8077,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"
           }
         }
       }
@@ -10747,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 (one-time display)."
+          },
+          "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.16.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,75 @@ 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.
+                Requires `BANKR_PARTNER_KEY` configured on the Vault service.
+                Default TTL 1 hour, max 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
     # ---------------------------------------------------------------------------
@@ -5150,23 +5219,52 @@ paths:
                             required: [provider, id_token]
                             properties:
                                 provider: { type: string, enum: [google, apple, discord] }
-                                id_token: { type: string }
+                                id_token:
+                                    type: string
+                                    description: Google/Apple ID token, or Discord OAuth authorization code
+                                oauth_redirect_uri:
+                                    type: string
+                                    description: Required for Discord — must match the redirect URI used in the OAuth flow
+                                auto_provision_chains:
+                                    type: array
+                                    items: { type: string }
             responses:
                 "200":
                     description: Login successful
                 "201":
                     description: New user created
+                "409":
+                    description: Email already registered (no auto-linking)
+                "401":
+                    description: Invalid or unverified token
 
     /v1/auth/passkeys/tx-assert/begin:
         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:
@@ -7029,6 +7127,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 (one-time display).
+                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.30.0",
+  "version": "0.32.0",
   "description": "OpenAPI 3.1.0 specification for the 1Claw Vault API — generate clients in any language",
   "license": "MIT",
   "repository": {