From a1d86d07ca1e343ebdc776e812258dad2295abd0 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Mon, 8 Jun 2026 11:36:11 +0000
Subject: [PATCH] feat(asm): add 403 Forbidden response to all endpoints
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Every endpoint was missing a 403 response, meaning SDK generators and
API clients had no contract for the "valid token, wrong permissions"
case — which is distinct from 401 and requires different handling
(show a permissions error rather than prompting re-auth).

Adds a reusable Forbidden component to components/responses and
references it from all 11 endpoints in the ASM spec.

https://claude.ai/code/session_01NSCBkwTnx3dp2co9rQjpWg
---
 asm/openapi.yaml | 34 ++++++++++++++++++++++++++++++++++
 1 file changed, 34 insertions(+)

diff --git a/asm/openapi.yaml b/asm/openapi.yaml
index 3673084..17ae12c 100644
--- a/asm/openapi.yaml
+++ b/asm/openapi.yaml
@@ -99,6 +99,8 @@ paths:
                           $ref: '#/components/schemas/Asset'
         '401':
           $ref: '#/components/responses/Unauthorized'
+        '403':
+          $ref: '#/components/responses/Forbidden'
         '429':
           $ref: '#/components/responses/RateLimited'
 
@@ -119,6 +121,8 @@ paths:
                 $ref: '#/components/schemas/AssetDetail'
         '401':
           $ref: '#/components/responses/Unauthorized'
+        '403':
+          $ref: '#/components/responses/Forbidden'
         '404':
           $ref: '#/components/responses/NotFound'
     patch:
@@ -143,6 +147,8 @@ paths:
           $ref: '#/components/responses/BadRequest'
         '401':
           $ref: '#/components/responses/Unauthorized'
+        '403':
+          $ref: '#/components/responses/Forbidden'
         '404':
           $ref: '#/components/responses/NotFound'
     delete:
@@ -157,6 +163,8 @@ paths:
           description: Asset archived
         '401':
           $ref: '#/components/responses/Unauthorized'
+        '403':
+          $ref: '#/components/responses/Forbidden'
         '404':
           $ref: '#/components/responses/NotFound'
 
@@ -189,6 +197,8 @@ paths:
                           $ref: '#/components/schemas/Scan'
         '401':
           $ref: '#/components/responses/Unauthorized'
+        '403':
+          $ref: '#/components/responses/Forbidden'
     post:
       operationId: triggerScan
       summary: Trigger scan
@@ -213,6 +223,8 @@ paths:
           $ref: '#/components/responses/BadRequest'
         '401':
           $ref: '#/components/responses/Unauthorized'
+        '403':
+          $ref: '#/components/responses/Forbidden'
         '429':
           $ref: '#/components/responses/RateLimited'
 
@@ -239,6 +251,8 @@ paths:
                 $ref: '#/components/schemas/ScanDetail'
         '401':
           $ref: '#/components/responses/Unauthorized'
+        '403':
+          $ref: '#/components/responses/Forbidden'
         '404':
           $ref: '#/components/responses/NotFound'
 
@@ -292,6 +306,8 @@ paths:
                           $ref: '#/components/schemas/Vulnerability'
         '401':
           $ref: '#/components/responses/Unauthorized'
+        '403':
+          $ref: '#/components/responses/Forbidden'
 
   /vulnerabilities/{vuln_id}:
     parameters:
@@ -316,6 +332,8 @@ paths:
                 $ref: '#/components/schemas/VulnerabilityDetail'
         '401':
           $ref: '#/components/responses/Unauthorized'
+        '403':
+          $ref: '#/components/responses/Forbidden'
         '404':
           $ref: '#/components/responses/NotFound'
     patch:
@@ -340,6 +358,8 @@ paths:
           $ref: '#/components/responses/BadRequest'
         '401':
           $ref: '#/components/responses/Unauthorized'
+        '403':
+          $ref: '#/components/responses/Forbidden'
         '404':
           $ref: '#/components/responses/NotFound'
 
@@ -362,6 +382,8 @@ paths:
                       $ref: '#/components/schemas/Tag'
         '401':
           $ref: '#/components/responses/Unauthorized'
+        '403':
+          $ref: '#/components/responses/Forbidden'
     post:
       operationId: createTag
       summary: Create tag
@@ -392,6 +414,8 @@ paths:
           $ref: '#/components/responses/BadRequest'
         '401':
           $ref: '#/components/responses/Unauthorized'
+        '403':
+          $ref: '#/components/responses/Forbidden'
 
 components:
   securitySchemes:
@@ -438,6 +462,16 @@ components:
             error:
               code: unauthorized
               message: Invalid or missing Bearer token
+    Forbidden:
+      description: Valid API key but insufficient permissions for this action
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+          example:
+            error:
+              code: forbidden
+              message: Your API key does not have permission to perform this action
     NotFound:
       description: Resource not found
       content: