@1claw/openapi-spec 0.16.0 → 0.16.3

package/README.md

@@ -40,9 +40,11 @@ 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)
 
-- **Billing — LLM token billing** — `GET /v1/billing/llm-token-billing`, `POST .../subscribe`, `POST .../disable` (Stripe AI Gateway add-on; optional org feature)
+- **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)
+- **Billing — LLM token billing** — `GET /v1/billing/llm-token-billing` (`LlmTokenBillingStatus`: `enabled`, `subscription_status`, optional `credit_balance`, optional `billing_cycle_usage` with `metered_lines[]`), `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
 - **Secrets** — CRUD, versioning, CMEK-encrypted flag

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"
@@ -153,6 +153,7 @@
           "Authentication"
         ],
         "summary": "Exchange agent credentials for JWT",
+        "description": "Returns a short-lived EdDSA-signed JWT (`access_token`). Standard claims include `sub`\n(`agent:<uuid>`), `org`, `scopes`, `vault_ids`, optional `intents_api_enabled`, optional\n`shroud_enabled`, optional `llm_token_billing` / `stripe_customer_id` when org LLM billing is on.\n\nWhen **`shroud_enabled`** is true, the JWT payload may include **`shroud_config`**: a JSON object\nmirroring the agent row in Vault (same shape as `ShroudConfig` on `GET /v1/agents/{id}`).\n**Shroud** (TEE proxy) decodes this on each LLM request and runs **PolicyEngine** after the\nglobal inspection pipeline so per-agent limits and threat **block** actions apply without a\nseparate policy fetch. Re-exchange the agent token after changing `shroud_config` so the JWT\nis fresh.\n\nUser JWTs from password, API key, or device flow do **not** include `shroud_config`.\n",
         "operationId": "agentToken",
         "security": [],
         "requestBody": {
@@ -375,6 +376,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": [
@@ -2825,7 +2894,7 @@
         ],
         "summary": "Get LLM token billing status",
         "operationId": "getLlmTokenBilling",
-        "description": "Returns whether LLM token billing is enabled for the caller's org.",
+        "description": "Returns whether LLM token billing is enabled, optional Stripe billing credit balance (metered scope), and estimated cycle usage from the upcoming invoice—including per-line metered rows when Stripe returns them (amounts; quantities such as tokens when present).\n",
         "responses": {
           "200": {
             "description": "LLM token billing status",
@@ -3839,6 +3908,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 +4162,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 +4368,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": {
@@ -6545,8 +6778,83 @@
           }
         }
       },
+      "LlmMeteredInvoiceLine": {
+        "type": "object",
+        "description": "Metered line from Stripe upcoming invoice (usage detail when available).",
+        "properties": {
+          "description": {
+            "type": "string",
+            "nullable": true
+          },
+          "amount_cents": {
+            "type": "integer",
+            "format": "int64"
+          },
+          "quantity": {
+            "type": "number",
+            "nullable": true,
+            "description": "Billed usage units when Stripe returns quantity (e.g. tokens)."
+          },
+          "price_nickname": {
+            "type": "string",
+            "nullable": true
+          }
+        }
+      },
+      "LlmBillingCycleUsage": {
+        "type": "object",
+        "description": "Accrued LLM charges for the current Stripe subscription period (upcoming invoice).",
+        "properties": {
+          "period_start": {
+            "type": "string",
+            "format": "date-time",
+            "nullable": true
+          },
+          "period_end": {
+            "type": "string",
+            "format": "date-time",
+            "nullable": true
+          },
+          "accrued_usage_cents": {
+            "type": "integer",
+            "format": "int64"
+          },
+          "currency": {
+            "type": "string"
+          },
+          "metered_lines": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/LlmMeteredInvoiceLine"
+            }
+          }
+        }
+      },
+      "LlmCreditBalance": {
+        "type": "object",
+        "properties": {
+          "available_cents": {
+            "type": "integer",
+            "format": "int64"
+          },
+          "ledger_cents": {
+            "type": "integer",
+            "format": "int64"
+          },
+          "used_cents": {
+            "type": "integer",
+            "format": "int64"
+          },
+          "currency": {
+            "type": "string"
+          }
+        }
+      },
       "LlmTokenBillingStatus": {
         "type": "object",
+        "required": [
+          "enabled"
+        ],
         "properties": {
           "enabled": {
             "type": "boolean"
@@ -6557,6 +6865,12 @@
               "active",
               "inactive"
             ]
+          },
+          "credit_balance": {
+            "$ref": "#/components/schemas/LlmCreditBalance"
+          },
+          "billing_cycle_usage": {
+            "$ref": "#/components/schemas/LlmBillingCycleUsage"
           }
         }
       },

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,
@@ -105,6 +105,19 @@ paths:
         post:
             tags: [Authentication]
             summary: Exchange agent credentials for JWT
+            description: |
+                Returns a short-lived EdDSA-signed JWT (`access_token`). Standard claims include `sub`
+                (`agent:<uuid>`), `org`, `scopes`, `vault_ids`, optional `intents_api_enabled`, optional
+                `shroud_enabled`, optional `llm_token_billing` / `stripe_customer_id` when org LLM billing is on.
+
+                When **`shroud_enabled`** is true, the JWT payload may include **`shroud_config`**: a JSON object
+                mirroring the agent row in Vault (same shape as `ShroudConfig` on `GET /v1/agents/{id}`).
+                **Shroud** (TEE proxy) decodes this on each LLM request and runs **PolicyEngine** after the
+                global inspection pipeline so per-agent limits and threat **block** actions apply without a
+                separate policy fetch. Re-exchange the agent token after changing `shroud_config` so the JWT
+                is fresh.
+
+                User JWTs from password, API key, or device flow do **not** include `shroud_config`.
             operationId: agentToken
             security: []
             requestBody:
@@ -245,6 +258,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]
@@ -1809,7 +1867,10 @@ paths:
             tags: [Billing]
             summary: Get LLM token billing status
             operationId: getLlmTokenBilling
-            description: Returns whether LLM token billing is enabled for the caller's org.
+            description: >
+                Returns whether LLM token billing is enabled, optional Stripe billing credit balance
+                (metered scope), and estimated cycle usage from the upcoming invoice—including per-line
+                metered rows when Stripe returns them (amounts; quantities such as tokens when present).
             responses:
                 "200":
                     description: LLM token billing status
@@ -2452,6 +2513,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 +2700,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 +2837,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:
@@ -4329,14 +4503,74 @@ components:
                 limit:
                     type: integer
 
+        LlmMeteredInvoiceLine:
+            type: object
+            description: Metered line from Stripe upcoming invoice (usage detail when available).
+            properties:
+                description:
+                    type: string
+                    nullable: true
+                amount_cents:
+                    type: integer
+                    format: int64
+                quantity:
+                    type: number
+                    nullable: true
+                    description: Billed usage units when Stripe returns quantity (e.g. tokens).
+                price_nickname:
+                    type: string
+                    nullable: true
+
+        LlmBillingCycleUsage:
+            type: object
+            description: Accrued LLM charges for the current Stripe subscription period (upcoming invoice).
+            properties:
+                period_start:
+                    type: string
+                    format: date-time
+                    nullable: true
+                period_end:
+                    type: string
+                    format: date-time
+                    nullable: true
+                accrued_usage_cents:
+                    type: integer
+                    format: int64
+                currency:
+                    type: string
+                metered_lines:
+                    type: array
+                    items:
+                        $ref: "#/components/schemas/LlmMeteredInvoiceLine"
+
+        LlmCreditBalance:
+            type: object
+            properties:
+                available_cents:
+                    type: integer
+                    format: int64
+                ledger_cents:
+                    type: integer
+                    format: int64
+                used_cents:
+                    type: integer
+                    format: int64
+                currency:
+                    type: string
+
         LlmTokenBillingStatus:
             type: object
+            required: [enabled]
             properties:
                 enabled:
                     type: boolean
                 subscription_status:
                     type: string
                     enum: [active, inactive]
+                credit_balance:
+                    $ref: "#/components/schemas/LlmCreditBalance"
+                billing_cycle_usage:
+                    $ref: "#/components/schemas/LlmBillingCycleUsage"
 
         LlmCheckoutResponse:
             type: object

package/package.json

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