From b1a02e242bf64ddbd4b8ca75d703bcea3f8119da Mon Sep 17 00:00:00 2001
From: Matt Miller <mattmiller@comfy.org>
Date: Tue, 19 May 2026 16:45:58 -0700
Subject: [PATCH] docs(openapi): tighten workspace API key description field
 (BE-1004)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Aligns the OSS spec with the cloud-side BE-1004 contract:

- createWorkspaceApiKey request body: add maxLength: 5000 to the
  description property (matches cloud's hub_profile.description
  MaxLen(5000) convention; enforced cloud-side via handler check).
- WorkspaceApiKey + WorkspaceApiKeyCreated response schemas:
  mark description as required (cloud's handler always populates
  the field, defaulting to empty string when not supplied on create),
  drop nullable: true, add maxLength: 5000 for symmetry, and clarify
  the doc string ("Always present in responses; empty string when no
  description was supplied on create").

Both schemas are tagged x-runtime: [cloud] at the schema level so the
tightening is correctly scoped — OSS-only implementations are not
required to honor the workspace API keys endpoints at all.

Related cloud PR: Comfy-Org/cloud#3747
---
 openapi.yaml | 13 ++++++++-----
 1 file changed, 8 insertions(+), 5 deletions(-)

diff --git a/openapi.yaml b/openapi.yaml
index bc1ae16fa..2658b9b86 100644
--- a/openapi.yaml
+++ b/openapi.yaml
@@ -4162,7 +4162,8 @@ paths:
                   description: Display name for the API key
                 description:
                   type: string
-                  description: User-provided description for the key
+                  description: User-provided description of the key's purpose
+                  maxLength: 5000
       responses:
         "201":
           description: API key created
@@ -7680,6 +7681,7 @@ components:
       required:
         - id
         - name
+        - description
       properties:
         id:
           type: string
@@ -7687,8 +7689,8 @@ components:
           type: string
         description:
           type: string
-          nullable: true
-          description: User-provided description
+          maxLength: 5000
+          description: User-provided description of the key's purpose. Always present in responses; empty string when no description was supplied on create.
         prefix:
           type: string
           description: First few characters of the key for identification
@@ -7709,6 +7711,7 @@ components:
       required:
         - id
         - name
+        - description
         - key
       properties:
         id:
@@ -7717,8 +7720,8 @@ components:
           type: string
         description:
           type: string
-          nullable: true
-          description: User-provided description
+          maxLength: 5000
+          description: User-provided description of the key's purpose. Always present in responses; empty string when no description was supplied on create.
         key:
           type: string
           description: Full API key value (only returned on creation)