docs(access-requests): describe resource_reference as alternative to resource_id in schema

.secrets.baseline

@@ -324,7 +324,7 @@
         "filename": "openapi/control/control.openapi.yaml",
         "hashed_secret": "2c4ea53d93a5d7661383e1c667d72270f9bf2fb6",
         "is_verified": false,
-        "line_number": 15827
+        "line_number": 15829
       }
     ],
     "src/jentic_one/auth/services/crypto.py": [
@@ -1544,5 +1544,5 @@
       }
     ]
   },
-  "generated_at": "2026-07-01T16:24:17Z"
+  "generated_at": "2026-07-10T14:14:28Z"
 }

openapi/control/control.openapi.yaml

@@ -70,12 +70,14 @@ components:
           anyOf:
           - type: string
           - type: 'null'
+          description: Explicit ID of the resource (e.g. a toolkit tk_… or credential cred_… ID). For toolkit:bind, you can omit this and use resource_reference instead.
           title: Resource Id
         resource_reference:
           anyOf:
           - additionalProperties: true
             type: object
           - type: 'null'
+          description: Look up the resource by API identity instead of by ID. For toolkit:bind, provide {vendor, name, version} to resolve the toolkit that serves the given API. Use this when you don't know the toolkit ID.
           title: Resource Reference
         resource_type:
           enum:

src/jentic_one/control/web/schemas/access_requests.py

@@ -45,8 +45,17 @@ class AccessRequestItemRequest(BaseModel):
 
     resource_type: Literal["credential", "toolkit", "scope"]
     action: Literal["bind", "grant"]
-    resource_id: str | None = None
-    resource_reference: dict[str, Any] | None = None
+    resource_id: str | None = Field(
+        default=None,
+        description="Explicit ID of the resource (e.g. a toolkit tk_… or credential cred_… ID)."
+        " For toolkit:bind, you can omit this and use resource_reference instead.",
+    )
+    resource_reference: dict[str, Any] | None = Field(
+        default=None,
+        description="Look up the resource by API identity instead of by ID."
+        " For toolkit:bind, provide {vendor, name, version} to resolve the toolkit"
+        " that serves the given API. Use this when you don't know the toolkit ID.",
+    )
     to_type: str | None = None
     to_id: str | None = None
     rules: list[PermissionRuleSchema] | None = None

ui/openapi.json

@@ -98,6 +98,7 @@
                 "type": "null"
               }
             ],
+            "description": "Explicit ID of the resource (e.g. a toolkit tk_… or credential cred_… ID). For toolkit:bind, you can omit this and use resource_reference instead.",
             "title": "Resource Id"
           },
           "resource_reference": {
@@ -110,6 +111,7 @@
                 "type": "null"
               }
             ],
+            "description": "Look up the resource by API identity instead of by ID. For toolkit:bind, provide {vendor, name, version} to resolve the toolkit that serves the given API. Use this when you don't know the toolkit ID.",
             "title": "Resource Reference"
           },
           "resource_type": {

ui/src/shared/api/generated/models/AccessRequestItemRequest.ts

@@ -8,7 +8,13 @@ import type { jentic_one__control__web__schemas__access_requests__PermissionRule
  */
 export type AccessRequestItemRequest = {
     action: AccessRequestItemRequest.action;
+    /**
+     * Explicit ID of the resource (e.g. a toolkit tk_… or credential cred_… ID). For toolkit:bind, you can omit this and use resource_reference instead.
+     */
     resource_id?: (string | null);
+    /**
+     * Look up the resource by API identity instead of by ID. For toolkit:bind, provide {vendor, name, version} to resolve the toolkit that serves the given API. Use this when you don't know the toolkit ID.
+     */
     resource_reference?: (Record<string, any> | null);
     resource_type: AccessRequestItemRequest.resource_type;
     rules?: (Array<jentic_one__control__web__schemas__access_requests__PermissionRuleSchema> | null);