@1claw/openapi-spec 0.16.0 → 0.16.1

package/README.md

@@ -40,8 +40,9 @@ openapi-generator generate \
 import spec from "@1claw/openapi-spec/openapi.json";
 ```
 
-## What's in the spec (v0.15.x)
+## What's in the spec (v0.16.x)
 
+- **Auth — password reset** — `POST /v1/auth/forgot-password`, `POST /v1/auth/reset-password` (public; anti-enumeration on forgot)
 - **Billing — LLM token billing** — `GET /v1/billing/llm-token-billing`, `POST .../subscribe`, `POST .../disable` (Stripe AI Gateway add-on; optional org feature)
 - **Treasury** — Safe multisig treasuries: `POST/GET /v1/treasury`, `GET/PATCH/DELETE /v1/treasury/{id}`, signers, agent access requests (`requests[]` on list)
 - **Vaults** — CRUD, CMEK enable/disable, key rotation with job tracking

package/openapi.json

@@ -2,7 +2,7 @@
   "openapi": "3.1.0",
   "info": {
     "title": "1Claw API",
-    "version": "2.5.0",
+    "version": "2.6.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"
@@ -375,6 +375,74 @@
         }
       }
     },
+    "/v1/auth/forgot-password": {
+      "post": {
+        "tags": [
+          "Authentication"
+        ],
+        "summary": "Request password reset email",
+        "description": "Always returns the same message whether or not the email exists (no account enumeration).\nOnly password-based accounts receive mail.\n",
+        "operationId": "forgotPassword",
+        "security": [],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/ForgotPasswordRequest"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Acknowledgement (check email if account exists)",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ForgotPasswordResponse"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/v1/auth/reset-password": {
+      "post": {
+        "tags": [
+          "Authentication"
+        ],
+        "summary": "Set a new password using reset token from email",
+        "operationId": "resetPassword",
+        "security": [],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/ResetPasswordRequest"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Password updated",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ResetPasswordResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          }
+        }
+      }
+    },
     "/v1/auth/google": {
       "post": {
         "tags": [
@@ -3839,6 +3907,72 @@
         }
       }
     },
+    "/v1/admin/usage/reset": {
+      "post": {
+        "tags": [
+          "Admin"
+        ],
+        "summary": "Reset all API usage events (testing)",
+        "operationId": "adminResetUsageEvents",
+        "description": "Deletes every row in `usage_events` for all organizations. Resets monthly\nrequest counts used for free-tier / x402 quota. Does not change prepaid credit\nbalances or Stripe. **Platform admin only** (same guard as other `/v1/admin/*` routes).\n",
+        "responses": {
+          "200": {
+            "description": "Usage table cleared; returns number of deleted rows",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ResetUsageEventsResponse"
+                }
+              }
+            }
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          }
+        }
+      }
+    },
+    "/v1/admin/usage/reset-for-user": {
+      "post": {
+        "tags": [
+          "Admin"
+        ],
+        "summary": "Reset API usage for a user's organization",
+        "operationId": "adminResetUsageForUserByEmail",
+        "description": "Looks up a registered user by email and deletes all `usage_events` rows for that\nuser's `org_id`. Resets free-tier / monthly quota for the whole org (not other orgs).\n**Platform admin only.**\n",
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/ResetUsageForUserEmailRequest"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Usage cleared for the user's org",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ResetUsageForUserEmailResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        }
+      }
+    },
     "/v1/health": {
       "get": {
         "tags": [
@@ -4027,6 +4161,61 @@
           }
         }
       },
+      "ResetUsageEventsResponse": {
+        "type": "object",
+        "required": [
+          "deleted_events"
+        ],
+        "properties": {
+          "deleted_events": {
+            "type": "integer",
+            "format": "int64",
+            "description": "Number of usage_events rows removed"
+          }
+        }
+      },
+      "ResetUsageForUserEmailRequest": {
+        "type": "object",
+        "required": [
+          "email"
+        ],
+        "properties": {
+          "email": {
+            "type": "string",
+            "format": "email"
+          }
+        }
+      },
+      "ResetUsageForUserEmailResponse": {
+        "type": "object",
+        "required": [
+          "deleted_events",
+          "org_id",
+          "user_id",
+          "email",
+          "display_name"
+        ],
+        "properties": {
+          "deleted_events": {
+            "type": "integer",
+            "format": "int64"
+          },
+          "org_id": {
+            "type": "string",
+            "format": "uuid"
+          },
+          "user_id": {
+            "type": "string",
+            "format": "uuid"
+          },
+          "email": {
+            "type": "string"
+          },
+          "display_name": {
+            "type": "string"
+          }
+        }
+      },
       "LoginRequest": {
         "type": "object",
         "required": [
@@ -4178,6 +4367,49 @@
           }
         }
       },
+      "ForgotPasswordRequest": {
+        "type": "object",
+        "required": [
+          "email"
+        ],
+        "properties": {
+          "email": {
+            "type": "string",
+            "format": "email"
+          }
+        }
+      },
+      "ForgotPasswordResponse": {
+        "type": "object",
+        "properties": {
+          "message": {
+            "type": "string"
+          }
+        }
+      },
+      "ResetPasswordRequest": {
+        "type": "object",
+        "required": [
+          "token",
+          "new_password"
+        ],
+        "properties": {
+          "token": {
+            "type": "string"
+          },
+          "new_password": {
+            "type": "string"
+          }
+        }
+      },
+      "ResetPasswordResponse": {
+        "type": "object",
+        "properties": {
+          "message": {
+            "type": "string"
+          }
+        }
+      },
       "MfaStatusResponse": {
         "type": "object",
         "properties": {

package/openapi.yaml

@@ -2,7 +2,7 @@ openapi: 3.1.0
 
 info:
     title: 1Claw API
-    version: 2.5.0
+    version: 2.6.0
     description: |
         Secure secret management for AI agents. Provides vaults, secrets,
         policy-based access control, agent identity, Intents API,
@@ -245,6 +245,51 @@ paths:
                 "400":
                     $ref: "#/components/responses/BadRequest"
 
+    /v1/auth/forgot-password:
+        post:
+            tags: [Authentication]
+            summary: Request password reset email
+            description: |
+                Always returns the same message whether or not the email exists (no account enumeration).
+                Only password-based accounts receive mail.
+            operationId: forgotPassword
+            security: []
+            requestBody:
+                required: true
+                content:
+                    application/json:
+                        schema:
+                            $ref: "#/components/schemas/ForgotPasswordRequest"
+            responses:
+                "200":
+                    description: Acknowledgement (check email if account exists)
+                    content:
+                        application/json:
+                            schema:
+                                $ref: "#/components/schemas/ForgotPasswordResponse"
+
+    /v1/auth/reset-password:
+        post:
+            tags: [Authentication]
+            summary: Set a new password using reset token from email
+            operationId: resetPassword
+            security: []
+            requestBody:
+                required: true
+                content:
+                    application/json:
+                        schema:
+                            $ref: "#/components/schemas/ResetPasswordRequest"
+            responses:
+                "200":
+                    description: Password updated
+                    content:
+                        application/json:
+                            schema:
+                                $ref: "#/components/schemas/ResetPasswordResponse"
+                "400":
+                    $ref: "#/components/responses/BadRequest"
+
     /v1/auth/google:
         post:
             tags: [Authentication]
@@ -2452,6 +2497,54 @@ paths:
                 "403":
                     $ref: "#/components/responses/Forbidden"
 
+    /v1/admin/usage/reset:
+        post:
+            tags: [Admin]
+            summary: Reset all API usage events (testing)
+            operationId: adminResetUsageEvents
+            description: |
+                Deletes every row in `usage_events` for all organizations. Resets monthly
+                request counts used for free-tier / x402 quota. Does not change prepaid credit
+                balances or Stripe. **Platform admin only** (same guard as other `/v1/admin/*` routes).
+            responses:
+                "200":
+                    description: Usage table cleared; returns number of deleted rows
+                    content:
+                        application/json:
+                            schema:
+                                $ref: "#/components/schemas/ResetUsageEventsResponse"
+                "403":
+                    $ref: "#/components/responses/Forbidden"
+
+    /v1/admin/usage/reset-for-user:
+        post:
+            tags: [Admin]
+            summary: Reset API usage for a user's organization
+            operationId: adminResetUsageForUserByEmail
+            description: |
+                Looks up a registered user by email and deletes all `usage_events` rows for that
+                user's `org_id`. Resets free-tier / monthly quota for the whole org (not other orgs).
+                **Platform admin only.**
+            requestBody:
+                required: true
+                content:
+                    application/json:
+                        schema:
+                            $ref: "#/components/schemas/ResetUsageForUserEmailRequest"
+            responses:
+                "200":
+                    description: Usage cleared for the user's org
+                    content:
+                        application/json:
+                            schema:
+                                $ref: "#/components/schemas/ResetUsageForUserEmailResponse"
+                "400":
+                    $ref: "#/components/responses/BadRequest"
+                "403":
+                    $ref: "#/components/responses/Forbidden"
+                "404":
+                    $ref: "#/components/responses/NotFound"
+
     # ---------------------------------------------------------------------------
     # Health
     # ---------------------------------------------------------------------------
@@ -2591,6 +2684,42 @@ components:
                 detail:
                     type: string
 
+        ResetUsageEventsResponse:
+            type: object
+            required: [deleted_events]
+            properties:
+                deleted_events:
+                    type: integer
+                    format: int64
+                    description: Number of usage_events rows removed
+
+        ResetUsageForUserEmailRequest:
+            type: object
+            required: [email]
+            properties:
+                email:
+                    type: string
+                    format: email
+
+        ResetUsageForUserEmailResponse:
+            type: object
+            required:
+                [deleted_events, org_id, user_id, email, display_name]
+            properties:
+                deleted_events:
+                    type: integer
+                    format: int64
+                org_id:
+                    type: string
+                    format: uuid
+                user_id:
+                    type: string
+                    format: uuid
+                email:
+                    type: string
+                display_name:
+                    type: string
+
         # --- Auth ---
 
         LoginRequest:
@@ -2692,6 +2821,35 @@ components:
                 new_password:
                     type: string
 
+        ForgotPasswordRequest:
+            type: object
+            required: [email]
+            properties:
+                email:
+                    type: string
+                    format: email
+
+        ForgotPasswordResponse:
+            type: object
+            properties:
+                message:
+                    type: string
+
+        ResetPasswordRequest:
+            type: object
+            required: [token, new_password]
+            properties:
+                token:
+                    type: string
+                new_password:
+                    type: string
+
+        ResetPasswordResponse:
+            type: object
+            properties:
+                message:
+                    type: string
+
         # --- MFA ---
 
         MfaStatusResponse:

package/package.json

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