@1claw/openapi-spec 0.18.0 → 0.19.0

package/README.md

@@ -40,7 +40,7 @@ openapi-generator generate \
 import spec from "@1claw/openapi-spec/openapi.json";
 ```
 
-## What's in the spec (v0.18.0)
+## What's in the spec (v0.19.0)
 
 - **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.
 - **Auth — password reset** — `POST /v1/auth/forgot-password`, `POST /v1/auth/reset-password` (public; anti-enumeration on forgot)

package/openapi.json

@@ -2,7 +2,7 @@
   "openapi": "3.1.0",
   "info": {
     "title": "1Claw API",
-    "version": "2.8.0",
+    "version": "2.9.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"
@@ -1434,6 +1434,160 @@
         }
       }
     },
+    "/v1/vaults/{vault_id}/secret-versions/{path}": {
+      "get": {
+        "tags": [
+          "Secrets"
+        ],
+        "summary": "List all versions of a secret",
+        "operationId": "listSecretVersions",
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/VaultId"
+          },
+          {
+            "$ref": "#/components/parameters/SecretPath"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Version list",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/SecretVersionListResponse"
+                }
+              }
+            }
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        }
+      }
+    },
+    "/v1/vaults/{vault_id}/secret-version/{path}/{version}": {
+      "get": {
+        "tags": [
+          "Secrets"
+        ],
+        "summary": "Retrieve a specific version of a secret",
+        "operationId": "getSecretVersion",
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/VaultId"
+          },
+          {
+            "$ref": "#/components/parameters/SecretPath"
+          },
+          {
+            "name": "version",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "integer"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Decrypted secret value at the specified version",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/SecretResponse"
+                }
+              }
+            }
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          },
+          "410": {
+            "description": "Version has been disabled or expired"
+          }
+        }
+      }
+    },
+    "/v1/vaults/{vault_id}/secret-version/{path}/{version}/disable": {
+      "post": {
+        "tags": [
+          "Secrets"
+        ],
+        "summary": "Disable a specific secret version",
+        "operationId": "disableSecretVersion",
+        "description": "Disables a version so it can no longer be read. The version is\nretained for audit purposes but returns 410 on read attempts.\n",
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/VaultId"
+          },
+          {
+            "$ref": "#/components/parameters/SecretPath"
+          },
+          {
+            "name": "version",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "integer"
+            }
+          }
+        ],
+        "responses": {
+          "204": {
+            "description": "Version disabled"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        }
+      }
+    },
+    "/v1/vaults/{vault_id}/secret-rotate/{path}": {
+      "post": {
+        "tags": [
+          "Secrets"
+        ],
+        "summary": "Server-side secret rotation",
+        "operationId": "rotateSecret",
+        "description": "Generates a cryptographically random value and stores it as a new\nversion of the secret. The previous version is preserved in history.\nRequires rotate or write permission.\n",
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/VaultId"
+          },
+          {
+            "$ref": "#/components/parameters/SecretPath"
+          }
+        ],
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/RotateSecretRequest"
+              }
+            }
+          }
+        },
+        "responses": {
+          "201": {
+            "description": "New version created with server-generated value",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/SecretCreatedResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        }
+      }
+    },
     "/v1/vaults/{vault_id}/policies": {
       "post": {
         "tags": [
@@ -5143,6 +5297,10 @@
           "expires_at": {
             "type": "string",
             "format": "date-time"
+          },
+          "is_disabled": {
+            "type": "boolean",
+            "description": "Whether this version has been disabled (retained for audit but unreadable)"
           }
         }
       },
@@ -5247,6 +5405,42 @@
           }
         }
       },
+      "SecretVersionListResponse": {
+        "type": "object",
+        "properties": {
+          "versions": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/SecretMetadataResponse"
+            }
+          }
+        }
+      },
+      "RotateSecretRequest": {
+        "type": "object",
+        "properties": {
+          "length": {
+            "type": "integer",
+            "minimum": 8,
+            "maximum": 1024,
+            "description": "Length of the generated value (default 32)"
+          },
+          "charset": {
+            "type": "string",
+            "enum": [
+              "hex",
+              "base64",
+              "alphanumeric",
+              "ascii"
+            ],
+            "description": "Character set for the generated value (default hex)"
+          },
+          "type": {
+            "type": "string",
+            "description": "Override the secret type (defaults to existing secret's type)"
+          }
+        }
+      },
       "CreatePolicyRequest": {
         "type": "object",
         "required": [

package/openapi.yaml

@@ -2,7 +2,7 @@ openapi: 3.1.0
 
 info:
     title: 1Claw API
-    version: 2.8.0
+    version: 2.9.0
     description: |
         Secure secret management for AI agents. Provides vaults, secrets,
         policy-based access control, agent identity, Intents API,
@@ -937,6 +937,100 @@ paths:
                 "404":
                     $ref: "#/components/responses/NotFound"
 
+    /v1/vaults/{vault_id}/secret-versions/{path}:
+        get:
+            tags: [Secrets]
+            summary: List all versions of a secret
+            operationId: listSecretVersions
+            parameters:
+                - $ref: "#/components/parameters/VaultId"
+                - $ref: "#/components/parameters/SecretPath"
+            responses:
+                "200":
+                    description: Version list
+                    content:
+                        application/json:
+                            schema:
+                                $ref: "#/components/schemas/SecretVersionListResponse"
+                "404":
+                    $ref: "#/components/responses/NotFound"
+
+    /v1/vaults/{vault_id}/secret-version/{path}/{version}:
+        get:
+            tags: [Secrets]
+            summary: Retrieve a specific version of a secret
+            operationId: getSecretVersion
+            parameters:
+                - $ref: "#/components/parameters/VaultId"
+                - $ref: "#/components/parameters/SecretPath"
+                - name: version
+                  in: path
+                  required: true
+                  schema:
+                      type: integer
+            responses:
+                "200":
+                    description: Decrypted secret value at the specified version
+                    content:
+                        application/json:
+                            schema:
+                                $ref: "#/components/schemas/SecretResponse"
+                "404":
+                    $ref: "#/components/responses/NotFound"
+                "410":
+                    description: Version has been disabled or expired
+
+    /v1/vaults/{vault_id}/secret-version/{path}/{version}/disable:
+        post:
+            tags: [Secrets]
+            summary: Disable a specific secret version
+            operationId: disableSecretVersion
+            description: |
+                Disables a version so it can no longer be read. The version is
+                retained for audit purposes but returns 410 on read attempts.
+            parameters:
+                - $ref: "#/components/parameters/VaultId"
+                - $ref: "#/components/parameters/SecretPath"
+                - name: version
+                  in: path
+                  required: true
+                  schema:
+                      type: integer
+            responses:
+                "204":
+                    description: Version disabled
+                "404":
+                    $ref: "#/components/responses/NotFound"
+
+    /v1/vaults/{vault_id}/secret-rotate/{path}:
+        post:
+            tags: [Secrets]
+            summary: Server-side secret rotation
+            operationId: rotateSecret
+            description: |
+                Generates a cryptographically random value and stores it as a new
+                version of the secret. The previous version is preserved in history.
+                Requires rotate or write permission.
+            parameters:
+                - $ref: "#/components/parameters/VaultId"
+                - $ref: "#/components/parameters/SecretPath"
+            requestBody:
+                content:
+                    application/json:
+                        schema:
+                            $ref: "#/components/schemas/RotateSecretRequest"
+            responses:
+                "201":
+                    description: New version created with server-generated value
+                    content:
+                        application/json:
+                            schema:
+                                $ref: "#/components/schemas/SecretCreatedResponse"
+                "400":
+                    $ref: "#/components/responses/BadRequest"
+                "404":
+                    $ref: "#/components/responses/NotFound"
+
     # ---------------------------------------------------------------------------
     # Policies
     # ---------------------------------------------------------------------------
@@ -3370,6 +3464,9 @@ components:
                 expires_at:
                     type: string
                     format: date-time
+                is_disabled:
+                    type: boolean
+                    description: Whether this version has been disabled (retained for audit but unreadable)
 
         SecretCreatedResponse:
             description: Returned when a secret is created or updated. Extends SecretMetadataResponse with an optional client_share for MPC vaults.
@@ -3436,6 +3533,30 @@ components:
                     items:
                         $ref: "#/components/schemas/SecretMetadataResponse"
 
+        SecretVersionListResponse:
+            type: object
+            properties:
+                versions:
+                    type: array
+                    items:
+                        $ref: "#/components/schemas/SecretMetadataResponse"
+
+        RotateSecretRequest:
+            type: object
+            properties:
+                length:
+                    type: integer
+                    minimum: 8
+                    maximum: 1024
+                    description: Length of the generated value (default 32)
+                charset:
+                    type: string
+                    enum: [hex, base64, alphanumeric, ascii]
+                    description: Character set for the generated value (default hex)
+                type:
+                    type: string
+                    description: Override the secret type (defaults to existing secret's type)
+
         # --- Policies ---
 
         CreatePolicyRequest:

package/package.json

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