@1claw/openapi-spec 0.40.0 → 0.41.0

package/openapi.json

@@ -2,7 +2,7 @@
   "openapi": "3.1.0",
   "info": {
     "title": "1Claw API",
-    "version": "2.26.0",
+    "version": "2.27.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"
@@ -4116,6 +4116,66 @@
         }
       }
     },
+    "/v1/agents/{agent_id}/bindings/{binding_id}/rotate-credential": {
+      "post": {
+        "tags": [
+          "Execution Intents"
+        ],
+        "summary": "Rotate a binding credential",
+        "description": "Overwrite the stored credential for a binding without touching its config or guardrails. Human-only. The credential value is never returned.",
+        "operationId": "rotateBindingCredential",
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/AgentId"
+          },
+          {
+            "name": "binding_id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "format": "uuid"
+            }
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "required": [
+                  "credential"
+                ],
+                "properties": {
+                  "credential": {
+                    "description": "New credential material (object or string). Stored server-side."
+                  }
+                }
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Updated binding",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/BindingResponse"
+                }
+              }
+            }
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        }
+      }
+    },
     "/v1/agents/{agent_id}/execute": {
       "post": {
         "tags": [
@@ -17038,6 +17098,39 @@
           }
         }
       },
+      "CredentialSource": {
+        "type": "object",
+        "required": [
+          "type"
+        ],
+        "description": "Credential source — inline value (stored in __agent-keys) or live pointer to a vault secret (resolved at execution time).",
+        "discriminator": {
+          "propertyName": "type"
+        },
+        "properties": {
+          "type": {
+            "type": "string",
+            "enum": [
+              "inline",
+              "vault_ref"
+            ]
+          },
+          "value": {
+            "type": "object",
+            "additionalProperties": true,
+            "description": "For inline — the credential value object."
+          },
+          "vault_id": {
+            "type": "string",
+            "format": "uuid",
+            "description": "For vault_ref — the vault containing the referenced secret."
+          },
+          "path": {
+            "type": "string",
+            "description": "For vault_ref — the secret path in the vault."
+          }
+        }
+      },
       "CreateBindingRequest": {
         "type": "object",
         "required": [
@@ -17073,7 +17166,11 @@
           },
           "credential": {
             "type": "object",
-            "additionalProperties": true
+            "additionalProperties": true,
+            "description": "Legacy: inline credential value. Use credential_source for new integrations."
+          },
+          "credential_source": {
+            "$ref": "#/components/schemas/CredentialSource"
           }
         }
       },
@@ -17093,7 +17190,11 @@
           },
           "credential": {
             "type": "object",
-            "additionalProperties": true
+            "additionalProperties": true,
+            "description": "Legacy: inline credential value."
+          },
+          "credential_source": {
+            "$ref": "#/components/schemas/CredentialSource"
           }
         }
       },
@@ -17146,6 +17247,30 @@
           "is_active": {
             "type": "boolean"
           },
+          "credential_set": {
+            "type": "boolean",
+            "description": "Whether a credential is stored for this binding. The value itself is never returned."
+          },
+          "credential_source_type": {
+            "type": "string",
+            "enum": [
+              "inline",
+              "vault_ref"
+            ],
+            "nullable": true,
+            "description": "How the credential is sourced — inline (HSM-encrypted copy) or vault_ref (live pointer)."
+          },
+          "credential_vault_id": {
+            "type": "string",
+            "format": "uuid",
+            "nullable": true,
+            "description": "For vault_ref credentials — the vault containing the referenced secret."
+          },
+          "credential_path": {
+            "type": "string",
+            "nullable": true,
+            "description": "For vault_ref credentials — the secret path in the referenced vault."
+          },
           "created_at": {
             "type": "string",
             "format": "date-time"
@@ -17237,6 +17362,14 @@
           },
           "redactions_applied": {
             "type": "integer"
+          },
+          "execution_surface": {
+            "type": "string",
+            "enum": [
+              "vault",
+              "tee"
+            ],
+            "description": "Where the intent actually ran. Reported truthfully — never claims TEE when it ran in the Vault."
           }
         }
       },

package/openapi.yaml

@@ -2,7 +2,7 @@ openapi: 3.1.0
 
 info:
     title: 1Claw API
-    version: 2.26.0
+    version: 2.27.0
     description: |
         Secure secret management for AI agents. Provides vaults, secrets,
         policy-based access control, agent identity, Intents API,
@@ -2689,6 +2689,42 @@ paths:
                 "404":
                     $ref: "#/components/responses/NotFound"
 
+    /v1/agents/{agent_id}/bindings/{binding_id}/rotate-credential:
+        post:
+            tags: [Execution Intents]
+            summary: Rotate a binding credential
+            description: Overwrite the stored credential for a binding without touching its config or guardrails. Human-only. The credential value is never returned.
+            operationId: rotateBindingCredential
+            parameters:
+                - $ref: "#/components/parameters/AgentId"
+                - name: binding_id
+                  in: path
+                  required: true
+                  schema:
+                      type: string
+                      format: uuid
+            requestBody:
+                required: true
+                content:
+                    application/json:
+                        schema:
+                            type: object
+                            required: [credential]
+                            properties:
+                                credential:
+                                    description: New credential material (object or string). Stored server-side.
+            responses:
+                "200":
+                    description: Updated binding
+                    content:
+                        application/json:
+                            schema:
+                                $ref: "#/components/schemas/BindingResponse"
+                "403":
+                    $ref: "#/components/responses/Forbidden"
+                "404":
+                    $ref: "#/components/responses/NotFound"
+
     /v1/agents/{agent_id}/execute:
         post:
             tags: [Execution Intents]
@@ -11264,6 +11300,28 @@ components:
 
         # --- Execution Intents ---
 
+        CredentialSource:
+            type: object
+            required: [type]
+            description: Credential source — inline value (stored in __agent-keys) or live pointer to a vault secret (resolved at execution time).
+            discriminator:
+                propertyName: type
+            properties:
+                type:
+                    type: string
+                    enum: [inline, vault_ref]
+                value:
+                    type: object
+                    additionalProperties: true
+                    description: For inline — the credential value object.
+                vault_id:
+                    type: string
+                    format: uuid
+                    description: For vault_ref — the vault containing the referenced secret.
+                path:
+                    type: string
+                    description: For vault_ref — the secret path in the vault.
+
         CreateBindingRequest:
             type: object
             required: [name, binding_type]
@@ -11282,6 +11340,9 @@ components:
                 credential:
                     type: object
                     additionalProperties: true
+                    description: "Legacy: inline credential value. Use credential_source for new integrations."
+                credential_source:
+                    $ref: "#/components/schemas/CredentialSource"
 
         UpdateBindingRequest:
             type: object
@@ -11297,6 +11358,9 @@ components:
                 credential:
                     type: object
                     additionalProperties: true
+                    description: "Legacy: inline credential value."
+                credential_source:
+                    $ref: "#/components/schemas/CredentialSource"
 
         BindingResponse:
             type: object
@@ -11321,6 +11385,23 @@ components:
                     additionalProperties: true
                 is_active:
                     type: boolean
+                credential_set:
+                    type: boolean
+                    description: Whether a credential is stored for this binding. The value itself is never returned.
+                credential_source_type:
+                    type: string
+                    enum: [inline, vault_ref]
+                    nullable: true
+                    description: How the credential is sourced — inline (HSM-encrypted copy) or vault_ref (live pointer).
+                credential_vault_id:
+                    type: string
+                    format: uuid
+                    nullable: true
+                    description: For vault_ref credentials — the vault containing the referenced secret.
+                credential_path:
+                    type: string
+                    nullable: true
+                    description: For vault_ref credentials — the secret path in the referenced vault.
                 created_at:
                     type: string
                     format: date-time
@@ -11380,6 +11461,10 @@ components:
                     type: integer
                 redactions_applied:
                     type: integer
+                execution_surface:
+                    type: string
+                    enum: [vault, tee]
+                    description: Where the intent actually ran. Reported truthfully — never claims TEE when it ran in the Vault.
 
         ExecutionEventResponse:
             type: object

package/package.json

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