@1claw/openapi-spec 0.32.1 → 0.34.0

package/openapi.yaml

@@ -70,6 +70,10 @@ tags:
       description: Event webhook registration and management
     - name: Platform
       description: Platform API for developers building on 1Claw (plt_ keys, user provisioning, bootstrap templates)
+    - name: OAuth
+      description: OAuth 2.0 authorization server (PKCE, consent, token exchange, OIDC UserInfo)
+    - name: Risk Engine
+      description: Risk events, verdicts, and honeytoken management
 
 # =============================================================================
 # PATHS
@@ -2804,6 +2808,48 @@ paths:
                 "404":
                     description: Agent-keys vault not found
 
+    /v1/org/bankr-config:
+        get:
+            tags: [Organization]
+            summary: Get org Bankr partner configuration
+            description: Returns whether the org has configured Bankr BYOK (partner key prefix and default wallet only — never the secret). Users only.
+            operationId: getOrgBankrConfig
+            responses:
+                "200":
+                    description: Bankr configuration status
+                    content:
+                        application/json:
+                            schema:
+                                $ref: "#/components/schemas/OrgBankrConfigResponse"
+        put:
+            tags: [Organization]
+            summary: Set org Bankr partner configuration
+            description: Store or replace the org's Bankr partner key (`bk_ptr_...`) and optional default wallet (`wlt_...`). Owner/admin only. Partner key encrypted at rest.
+            operationId: upsertOrgBankrConfig
+            requestBody:
+                required: true
+                content:
+                    application/json:
+                        schema:
+                            $ref: "#/components/schemas/UpsertOrgBankrConfigRequest"
+            responses:
+                "200":
+                    description: Configuration saved
+                    content:
+                        application/json:
+                            schema:
+                                $ref: "#/components/schemas/OrgBankrConfigResponse"
+        delete:
+            tags: [Organization]
+            summary: Remove org Bankr partner configuration
+            description: Delete BYOK credentials for the org. Owner/admin only.
+            operationId: deleteOrgBankrConfig
+            responses:
+                "204":
+                    description: Configuration removed
+                "404":
+                    description: Configuration not found
+
     /v1/org/invite:
         post:
             tags: [Organization]
@@ -3984,6 +4030,32 @@ paths:
                 "404":
                     $ref: "#/components/responses/NotFound"
 
+    /v1/treasury/wallets/spend-policy:
+        get:
+            tags: [Treasury Wallets]
+            summary: Get effective spend policy for current user
+            description: |
+                Returns the effective spend policy governing the authenticated user's
+                wallet transactions. Resolves from per-user override (if set) or the
+                app-wide default. Returns null if no policy is configured.
+            operationId: getEffectiveSpendPolicy
+            security:
+                - BearerAuth: []
+            responses:
+                "200":
+                    description: Effective spend policy
+                    content:
+                        application/json:
+                            schema:
+                                type: object
+                                properties:
+                                    policy:
+                                        nullable: true
+                                        allOf:
+                                            - $ref: "#/components/schemas/SpendPolicyResponse"
+                "401":
+                    $ref: "#/components/responses/Unauthorized"
+
     # ---------------------------------------------------------------------------
     # Webhooks
     # ---------------------------------------------------------------------------
@@ -4929,6 +5001,132 @@ paths:
                 "410":
                     description: Claim token has expired
 
+    # --- Spend Policies ---
+
+    /v1/platform/apps/{appId}/spend-policies:
+        post:
+            tags: [Platform]
+            summary: Create wallet spend policy
+            description: |
+                Create an app-wide spend policy that governs what embedded wallet users
+                can do with their wallets. Policies apply to all connected users by default
+                and can be overridden per-user via connection-level policies.
+            operationId: createSpendPolicy
+            security:
+                - BearerAuth: []
+            parameters:
+                - in: path
+                  name: appId
+                  required: true
+                  schema:
+                      type: string
+                      format: uuid
+            requestBody:
+                required: true
+                content:
+                    application/json:
+                        schema:
+                            $ref: "#/components/schemas/CreateSpendPolicyRequest"
+            responses:
+                "201":
+                    description: Spend policy created
+                    content:
+                        application/json:
+                            schema:
+                                $ref: "#/components/schemas/SpendPolicyResponse"
+                "400":
+                    $ref: "#/components/responses/BadRequest"
+                "403":
+                    $ref: "#/components/responses/Forbidden"
+        get:
+            tags: [Platform]
+            summary: List spend policies for app
+            description: Returns all spend policies configured for the platform app.
+            operationId: listSpendPolicies
+            security:
+                - BearerAuth: []
+            parameters:
+                - in: path
+                  name: appId
+                  required: true
+                  schema:
+                      type: string
+                      format: uuid
+            responses:
+                "200":
+                    description: Spend policies
+                    content:
+                        application/json:
+                            schema:
+                                type: object
+                                properties:
+                                    policies:
+                                        type: array
+                                        items:
+                                            $ref: "#/components/schemas/SpendPolicyResponse"
+
+    /v1/platform/apps/{appId}/spend-policies/{policyId}:
+        delete:
+            tags: [Platform]
+            summary: Delete a spend policy
+            operationId: deleteSpendPolicy
+            security:
+                - BearerAuth: []
+            parameters:
+                - in: path
+                  name: appId
+                  required: true
+                  schema:
+                      type: string
+                      format: uuid
+                - in: path
+                  name: policyId
+                  required: true
+                  schema:
+                      type: string
+                      format: uuid
+            responses:
+                "204":
+                    description: Deleted
+                "404":
+                    $ref: "#/components/responses/NotFound"
+
+    /v1/platform/connections/{connectionId}/spend-policy:
+        put:
+            tags: [Platform]
+            summary: Set per-user spend policy override
+            description: |
+                Override the app-wide spend policy for a specific connected user. This
+                policy takes precedence over the app default. Remove by deleting the
+                connection-level policy.
+            operationId: setUserSpendPolicy
+            security:
+                - BearerAuth: []
+            parameters:
+                - in: path
+                  name: connectionId
+                  required: true
+                  schema:
+                      type: string
+                      format: uuid
+            requestBody:
+                required: true
+                content:
+                    application/json:
+                        schema:
+                            $ref: "#/components/schemas/CreateSpendPolicyRequest"
+            responses:
+                "200":
+                    description: Spend policy set
+                    content:
+                        application/json:
+                            schema:
+                                $ref: "#/components/schemas/SpendPolicyResponse"
+                "400":
+                    $ref: "#/components/responses/BadRequest"
+                "403":
+                    $ref: "#/components/responses/Forbidden"
+
     # --- Approvals ---
 
     /v1/approvals:
@@ -5281,7 +5479,419 @@ paths:
                 - BearerAuth: []
             responses:
                 "200":
-                    description: Passkey token for X-Passkey-Token header
+                    description: Passkey token for X-Passkey-Token header
+
+    # ---------------------------------------------------------------------------
+    # Email OTP
+    # ---------------------------------------------------------------------------
+
+    /v1/auth/email-otp/send:
+        post:
+            tags: [Authentication]
+            summary: Send email OTP code
+            description: |
+                Sends a 6-digit one-time code to the specified email address.
+                No authentication required. Rate-limited per IP and per email.
+            operationId: sendEmailOtp
+            security: []
+            requestBody:
+                required: true
+                content:
+                    application/json:
+                        schema:
+                            type: object
+                            required: [email]
+                            properties:
+                                email:
+                                    type: string
+                                    format: email
+                                platform_app_id:
+                                    type: string
+                                    format: uuid
+                                    description: Optional platform app context for embedded wallet flows
+            responses:
+                "200":
+                    description: OTP sent
+                    content:
+                        application/json:
+                            schema:
+                                type: object
+                                properties:
+                                    status:
+                                        type: string
+                                        enum: [sent]
+                "429":
+                    description: Rate limited
+
+    /v1/auth/email-otp/verify:
+        post:
+            tags: [Authentication]
+            summary: Verify email OTP and get JWT
+            description: |
+                Verifies the 6-digit code sent to the user's email. If the user does not
+                exist, a new account is created. Optionally auto-provisions treasury wallets
+                for the specified chains. Returns a JWT for subsequent API calls.
+            operationId: verifyEmailOtp
+            security: []
+            requestBody:
+                required: true
+                content:
+                    application/json:
+                        schema:
+                            type: object
+                            required: [email, code]
+                            properties:
+                                email:
+                                    type: string
+                                    format: email
+                                code:
+                                    type: string
+                                    description: 6-digit OTP code
+                                platform_app_id:
+                                    type: string
+                                    format: uuid
+                                auto_provision_chains:
+                                    type: array
+                                    items: { type: string }
+                                    description: Chains to auto-generate wallets for (e.g. ["ethereum", "base"])
+            responses:
+                "200":
+                    description: Existing user authenticated
+                    content:
+                        application/json:
+                            schema:
+                                $ref: "#/components/schemas/EmailOtpVerifyResponse"
+                "201":
+                    description: New user created and authenticated
+                    content:
+                        application/json:
+                            schema:
+                                $ref: "#/components/schemas/EmailOtpVerifyResponse"
+                "400":
+                    description: Invalid or expired code
+                "429":
+                    description: Rate limited
+
+    # ---------------------------------------------------------------------------
+    # OAuth
+    # ---------------------------------------------------------------------------
+
+    /v1/oauth/authorize:
+        get:
+            tags: [OAuth]
+            summary: Get OAuth consent info
+            description: |
+                Returns information about the platform app requesting authorization so the
+                UI can display a consent screen. Used by the 1Claw-hosted consent page.
+            operationId: getOAuthConsent
+            security:
+                - BearerAuth: []
+            parameters:
+                - name: client_id
+                  in: query
+                  required: true
+                  schema: { type: string }
+                  description: Platform app slug
+                - name: redirect_uri
+                  in: query
+                  required: true
+                  schema: { type: string, format: uri }
+                - name: response_type
+                  in: query
+                  required: true
+                  schema: { type: string, enum: [code] }
+                - name: scope
+                  in: query
+                  schema: { type: string }
+                  description: Space-delimited scopes (e.g. "openid email wallet")
+                - name: state
+                  in: query
+                  schema: { type: string }
+                - name: code_challenge
+                  in: query
+                  schema: { type: string }
+                  description: PKCE code challenge
+                - name: code_challenge_method
+                  in: query
+                  schema: { type: string, enum: [S256, plain] }
+                - name: nonce
+                  in: query
+                  schema: { type: string }
+                  description: OIDC nonce for ID token replay protection
+            responses:
+                "200":
+                    description: Consent screen data
+                    content:
+                        application/json:
+                            schema:
+                                $ref: "#/components/schemas/OAuthConsentResponse"
+                "400":
+                    description: Invalid client_id, redirect_uri, or response_type
+        post:
+            tags: [OAuth]
+            summary: Submit OAuth consent decision
+            description: |
+                The user approves or denies the authorization request. On approval, returns
+                a redirect URL containing the authorization code. On denial, returns a
+                redirect URL with an error parameter.
+            operationId: submitOAuthConsent
+            security:
+                - BearerAuth: []
+            requestBody:
+                required: true
+                content:
+                    application/json:
+                        schema:
+                            type: object
+                            required: [approve, client_id, redirect_uri]
+                            properties:
+                                approve: { type: boolean }
+                                client_id: { type: string }
+                                redirect_uri: { type: string, format: uri }
+                                scope: { type: string }
+                                state: { type: string }
+                                code_challenge: { type: string }
+                                code_challenge_method: { type: string, enum: [S256, plain] }
+                                nonce: { type: string }
+            responses:
+                "200":
+                    description: Redirect URL with authorization code or error
+                    content:
+                        application/json:
+                            schema:
+                                type: object
+                                required: [redirect_url]
+                                properties:
+                                    redirect_url:
+                                        type: string
+                                        format: uri
+                "400":
+                    description: Invalid request
+
+    /v1/oauth/token:
+        post:
+            tags: [OAuth]
+            summary: Exchange authorization code for tokens
+            description: |
+                Standard OAuth 2.0 token endpoint. Exchanges an authorization code for an
+                access token and optional OIDC ID token. Supports PKCE via `code_verifier`.
+            operationId: exchangeOAuthToken
+            security: []
+            requestBody:
+                required: true
+                content:
+                    application/json:
+                        schema:
+                            type: object
+                            required: [grant_type, code, client_id, redirect_uri]
+                            properties:
+                                grant_type:
+                                    type: string
+                                    enum: [authorization_code]
+                                code: { type: string }
+                                client_id: { type: string }
+                                redirect_uri: { type: string, format: uri }
+                                code_verifier:
+                                    type: string
+                                    description: PKCE code verifier (required when code_challenge was used)
+            responses:
+                "200":
+                    description: Token response
+                    content:
+                        application/json:
+                            schema:
+                                $ref: "#/components/schemas/OAuthTokenResponse"
+                "400":
+                    description: Invalid grant, code, or verifier
+                "401":
+                    description: Invalid client credentials
+
+    /v1/oauth/userinfo:
+        get:
+            tags: [OAuth]
+            summary: Get authenticated user info (OIDC UserInfo)
+            description: |
+                Standard OIDC UserInfo endpoint. Returns claims about the authenticated user
+                based on the granted scopes.
+            operationId: getOAuthUserInfo
+            security:
+                - BearerAuth: []
+            responses:
+                "200":
+                    description: User info
+                    content:
+                        application/json:
+                            schema:
+                                $ref: "#/components/schemas/OAuthUserInfoResponse"
+                "401":
+                    $ref: "#/components/responses/Unauthorized"
+
+    # ---------------------------------------------------------------------------
+    # Risk Engine
+    # ---------------------------------------------------------------------------
+
+    /v1/risk/events:
+        get:
+            tags: [Risk Engine]
+            summary: List risk events
+            description: |
+                Returns risk events detected by the risk engine, ordered by most recent first.
+                Filter by severity or principal type.
+            operationId: listRiskEvents
+            parameters:
+                - name: severity
+                  in: query
+                  schema:
+                      type: string
+                      enum: [low, medium, high, critical]
+                  description: Filter events by severity level
+                - name: principal_type
+                  in: query
+                  schema:
+                      type: string
+                      enum: [user, agent]
+                  description: Filter events by principal type
+                - name: limit
+                  in: query
+                  schema:
+                      type: integer
+                      default: 50
+                - name: offset
+                  in: query
+                  schema:
+                      type: integer
+                      default: 0
+            responses:
+                "200":
+                    description: Risk event list
+                    content:
+                        application/json:
+                            schema:
+                                $ref: "#/components/schemas/RiskEventListResponse"
+                "401":
+                    $ref: "#/components/responses/Unauthorized"
+
+    /v1/risk/verdicts:
+        get:
+            tags: [Risk Engine]
+            summary: List risk verdicts
+            description: Returns all active risk verdicts for the caller's organization.
+            operationId: listRiskVerdicts
+            responses:
+                "200":
+                    description: Verdict list
+                    content:
+                        application/json:
+                            schema:
+                                $ref: "#/components/schemas/RiskVerdictListResponse"
+                "401":
+                    $ref: "#/components/responses/Unauthorized"
+
+    /v1/risk/verdicts/{principal_type}/{principal_id}:
+        get:
+            tags: [Risk Engine]
+            summary: Get risk verdict for a principal
+            description: Returns the current risk verdict for a specific user or agent.
+            operationId: getRiskVerdict
+            parameters:
+                - name: principal_type
+                  in: path
+                  required: true
+                  schema:
+                      type: string
+                      enum: [user, agent]
+                - name: principal_id
+                  in: path
+                  required: true
+                  schema:
+                      type: string
+                      format: uuid
+            responses:
+                "200":
+                    description: Risk verdict (null if no verdict exists)
+                    content:
+                        application/json:
+                            schema:
+                                type: object
+                                properties:
+                                    verdict:
+                                        $ref: "#/components/schemas/RiskVerdict"
+                                        nullable: true
+                "401":
+                    $ref: "#/components/responses/Unauthorized"
+                "404":
+                    $ref: "#/components/responses/NotFound"
+
+    /v1/risk/honeytokens:
+        get:
+            tags: [Risk Engine]
+            summary: List honeytokens
+            description: Returns all honeytokens (canary secrets) configured for the caller's organization.
+            operationId: listHoneytokens
+            responses:
+                "200":
+                    description: Honeytoken list
+                    content:
+                        application/json:
+                            schema:
+                                $ref: "#/components/schemas/HoneytokenListResponse"
+                "401":
+                    $ref: "#/components/responses/Unauthorized"
+        post:
+            tags: [Risk Engine]
+            summary: Create a honeytoken
+            description: |
+                Register a secret path as a honeytoken (canary). Any access to this secret
+                triggers a risk event and increments the trigger counter.
+            operationId: createHoneytoken
+            requestBody:
+                required: true
+                content:
+                    application/json:
+                        schema:
+                            $ref: "#/components/schemas/CreateHoneytokenRequest"
+            responses:
+                "201":
+                    description: Honeytoken created
+                    content:
+                        application/json:
+                            schema:
+                                type: object
+                                properties:
+                                    honeytoken:
+                                        $ref: "#/components/schemas/Honeytoken"
+                "400":
+                    $ref: "#/components/responses/BadRequest"
+                "401":
+                    $ref: "#/components/responses/Unauthorized"
+
+    /v1/risk/honeytokens/{id}:
+        delete:
+            tags: [Risk Engine]
+            summary: Delete a honeytoken
+            description: Remove a honeytoken registration. The underlying secret is not affected.
+            operationId: deleteHoneytoken
+            parameters:
+                - name: id
+                  in: path
+                  required: true
+                  schema:
+                      type: string
+                      format: uuid
+            responses:
+                "200":
+                    description: Honeytoken deleted
+                    content:
+                        application/json:
+                            schema:
+                                type: object
+                                properties:
+                                    deleted:
+                                        type: boolean
+                "401":
+                    $ref: "#/components/responses/Unauthorized"
+                "404":
+                    $ref: "#/components/responses/NotFound"
 
 # =============================================================================
 # COMPONENTS
@@ -7644,6 +8254,32 @@ components:
                     type: string
                     format: uuid
 
+        OrgBankrConfigResponse:
+            type: object
+            properties:
+                configured:
+                    type: boolean
+                partner_key_prefix:
+                    type: string
+                default_wallet_id:
+                    type: string
+                updated_at:
+                    type: string
+                    format: date-time
+                using_platform_fallback:
+                    type: boolean
+
+        UpsertOrgBankrConfigRequest:
+            type: object
+            required: [partner_key]
+            properties:
+                partner_key:
+                    type: string
+                    description: Bankr partner API key (bk_ptr_...)
+                default_wallet_id:
+                    type: string
+                    description: Default provisioned wallet (wlt_...)
+
         # --- Billing ---
 
         UsageSummaryResponse:
@@ -9459,3 +10095,334 @@ components:
                 created_at:
                     type: string
                     format: date-time
+
+        # --- Email OTP ---
+
+        EmailOtpVerifyResponse:
+            type: object
+            required: [token, user_id, org_id, is_new_user, email]
+            properties:
+                token:
+                    type: string
+                    description: JWT access token
+                user_id:
+                    type: string
+                    format: uuid
+                org_id:
+                    type: string
+                    format: uuid
+                is_new_user:
+                    type: boolean
+                email:
+                    type: string
+                    format: email
+                wallet_address:
+                    type: string
+                    nullable: true
+                    description: Ethereum address if auto_provision_chains included an EVM chain
+
+        # --- OAuth ---
+
+        OAuthConsentResponse:
+            type: object
+            required: [app_name, app_slug, scopes, redirect_uri, already_consented]
+            properties:
+                app_name:
+                    type: string
+                app_slug:
+                    type: string
+                app_logo_url:
+                    type: string
+                    format: uri
+                    nullable: true
+                scopes:
+                    type: array
+                    items: { type: string }
+                redirect_uri:
+                    type: string
+                    format: uri
+                already_consented:
+                    type: boolean
+
+        OAuthTokenResponse:
+            type: object
+            required: [access_token, token_type, expires_in, scope]
+            properties:
+                access_token:
+                    type: string
+                token_type:
+                    type: string
+                    enum: [Bearer]
+                expires_in:
+                    type: integer
+                    description: Token lifetime in seconds
+                id_token:
+                    type: string
+                    nullable: true
+                    description: OIDC ID token (when openid scope was granted)
+                scope:
+                    type: string
+
+        OAuthUserInfoResponse:
+            type: object
+            required: [sub, email]
+            properties:
+                sub:
+                    type: string
+                    format: uuid
+                email:
+                    type: string
+                    format: email
+                name:
+                    type: string
+                    nullable: true
+                wallet_address:
+                    type: string
+                    nullable: true
+
+        # --- Spend Policies ---
+
+        CreateSpendPolicyRequest:
+            type: object
+            properties:
+                user_id:
+                    type: string
+                    format: uuid
+                    description: Scope to a specific user (app-level policies only)
+                to_allowlist:
+                    type: array
+                    items: { type: string }
+                    description: Permitted destination addresses (empty = unrestricted)
+                to_denylist:
+                    type: array
+                    items: { type: string }
+                    description: Blocked destination addresses
+                max_value_per_tx_eth:
+                    type: string
+                    description: Maximum value per transaction in ETH (decimal string)
+                daily_limit_eth:
+                    type: string
+                    description: Rolling 24h spend cap in ETH (decimal string)
+                allowed_chains:
+                    type: array
+                    items: { type: string }
+                    description: Chains the user may transact on (empty = all enabled)
+                allowed_tokens:
+                    type: array
+                    items: { type: string }
+                    description: Permitted ERC-20 token contract addresses
+                max_transactions_per_day:
+                    type: integer
+                    description: Maximum number of transactions per 24h window
+
+        SpendPolicyResponse:
+            type: object
+            required: [id, platform_app_id, created_at]
+            properties:
+                id:
+                    type: string
+                    format: uuid
+                platform_app_id:
+                    type: string
+                    format: uuid
+                user_id:
+                    type: string
+                    format: uuid
+                    nullable: true
+                to_allowlist:
+                    type: array
+                    items: { type: string }
+                to_denylist:
+                    type: array
+                    items: { type: string }
+                max_value_per_tx_eth:
+                    type: string
+                    nullable: true
+                daily_limit_eth:
+                    type: string
+                    nullable: true
+                allowed_chains:
+                    type: array
+                    items: { type: string }
+                allowed_tokens:
+                    type: array
+                    items: { type: string }
+                max_transactions_per_day:
+                    type: integer
+                    nullable: true
+                created_at:
+                    type: string
+                    format: date-time
+
+        # --- Risk Engine ---
+
+        RiskEvent:
+            type: object
+            required: [id, occurred_at, principal_type, principal_id, org_id, event_type, payload, created_at]
+            properties:
+                id:
+                    type: string
+                    format: uuid
+                occurred_at:
+                    type: string
+                    format: date-time
+                principal_type:
+                    type: string
+                    enum: [user, agent]
+                principal_id:
+                    type: string
+                    format: uuid
+                org_id:
+                    type: string
+                    format: uuid
+                event_type:
+                    type: string
+                    description: "Risk event type (e.g. first_seen, geo_velocity, honeytoken_access)"
+                ip:
+                    type: string
+                    nullable: true
+                asn:
+                    type: integer
+                    nullable: true
+                asn_org:
+                    type: string
+                    nullable: true
+                country_code:
+                    type: string
+                    nullable: true
+                region:
+                    type: string
+                    nullable: true
+                city:
+                    type: string
+                    nullable: true
+                latitude:
+                    type: number
+                    nullable: true
+                longitude:
+                    type: number
+                    nullable: true
+                user_agent:
+                    type: string
+                    nullable: true
+                payload:
+                    type: object
+                    additionalProperties: true
+                created_at:
+                    type: string
+                    format: date-time
+
+        RiskEventListResponse:
+            type: object
+            required: [events]
+            properties:
+                events:
+                    type: array
+                    items:
+                        $ref: "#/components/schemas/RiskEvent"
+
+        RiskVerdictReason:
+            type: object
+            required: [detector, severity, description]
+            properties:
+                detector:
+                    type: string
+                severity:
+                    type: string
+                description:
+                    type: string
+                metadata:
+                    type: object
+                    additionalProperties: true
+
+        RiskVerdict:
+            type: object
+            required: [principal_type, principal_id, org_id, score, severity, reasons, computed_at, expires_at]
+            properties:
+                principal_type:
+                    type: string
+                principal_id:
+                    type: string
+                    format: uuid
+                org_id:
+                    type: string
+                    format: uuid
+                score:
+                    type: number
+                    description: Composite risk score (0.0 – 100.0)
+                severity:
+                    type: string
+                    enum: [low, medium, high, critical]
+                reasons:
+                    type: array
+                    items:
+                        $ref: "#/components/schemas/RiskVerdictReason"
+                computed_at:
+                    type: string
+                    format: date-time
+                expires_at:
+                    type: string
+                    format: date-time
+
+        RiskVerdictListResponse:
+            type: object
+            required: [verdicts]
+            properties:
+                verdicts:
+                    type: array
+                    items:
+                        $ref: "#/components/schemas/RiskVerdict"
+
+        Honeytoken:
+            type: object
+            required: [id, vault_id, org_id, secret_path, created_by, created_at, triggered_count]
+            properties:
+                id:
+                    type: string
+                    format: uuid
+                vault_id:
+                    type: string
+                    format: uuid
+                org_id:
+                    type: string
+                    format: uuid
+                secret_path:
+                    type: string
+                created_by:
+                    type: string
+                    format: uuid
+                created_at:
+                    type: string
+                    format: date-time
+                notes:
+                    type: string
+                    nullable: true
+                triggered_count:
+                    type: integer
+                last_triggered_at:
+                    type: string
+                    format: date-time
+                    nullable: true
+
+        CreateHoneytokenRequest:
+            type: object
+            required: [vault_id, secret_path]
+            properties:
+                vault_id:
+                    type: string
+                    format: uuid
+                secret_path:
+                    type: string
+                    description: Vault secret path to monitor as a canary
+                notes:
+                    type: string
+                    description: Optional human-readable notes about this honeytoken
+
+        HoneytokenListResponse:
+            type: object
+            required: [honeytokens]
+            properties:
+                honeytokens:
+                    type: array
+                    items:
+                        $ref: "#/components/schemas/Honeytoken"