feat: better description and payload for hyok and byok

apis/cmk/cmk-ui.yaml

@@ -79,26 +79,39 @@ paths:
         - Keys
       summary: Create a new Key
       description: |
-        Generate and store a new Key or register a key from customer held keystore.
-        - For `Hold Your Own Key (HYOK)`, a native key identifier needs to be provided. In this case no new key
-        material is generated but the key is enrolled within KMS CMK.
+        Create a new cryptographic key. The API supports two key management models:
+
+        **BYOK (Bring Your Own Key)**
+        - Key material is imported into CMK-managed keystore
+
+        **HYOK (Hold Your Own Key)**
+        - Key remains in customer's keystore, CMK connects to it
+
+        Use the `type` field to specify which key model to use.
       requestBody:
-        description: Key request body
+        description: Key request body - see examples for BYOK and HYOK formats
         required: true
         content:
           application/json:
             schema:
               $ref: "#/components/schemas/Key"
             examples:
-              KeyRequest:
-                $ref: "#/components/examples/KeyRequest"
+              BYOKKeyRequest:
+                $ref: "#/components/examples/BYOKKeyRequest"
+              HYOKKeyRequest:
+                $ref: "#/components/examples/HYOKKeyRequest"
       responses:
         "201":
           description: Created
           content:
             application/json:
               schema:
                 $ref: "#/components/schemas/Key"
+              examples:
+                BYOKKeyResponse:
+                  $ref: "#/components/examples/BYOKKeyResponse"
+                HYOKKeyResponse:
+                  $ref: "#/components/examples/HYOKKeyResponse"
         "400":
           $ref: "#/components/responses/400"
         "403":
@@ -3079,26 +3092,95 @@ components:
                   message: Requested feature is not implemented.
                   id: 635e791c-7ea2-4fd8-9be6-3bab61b2e779
   examples:
-    KeyRequest:
+    BYOKKeyRequest:
+      summary: Create a BYOK (Bring Your Own Key) key
+      description: |
+        BYOK key creation request. The key material will be imported into CMK-managed keystore, initially with status PENDING_IMPORT.
+        Region is required to specify where the key will be created.
       value:
-        name: example_key_name
-        type: HYOK
+        name: byok_example_key
+        type: BYOK
         keyConfigurationID: 12345678-90ab-cdef-1234-567890abcdef
-        description: This key is used for DB key store encryption.
-        enabled: true
+        description: BYOK key for database encryption
         algorithm: AES256
-        provider: AWS
         region: eu-central-1
-    AWSBYOKRequest:
+    HYOKKeyRequest:
+      summary: Create a HYOK (Hold Your Own Key) key
+      description: |
+        HYOK key creation request. The key remains in customer's keystore.
+        NativeID is the customer-provided key identifier, and accessDetails configure
+        how CMK connects to the customer's keystore.
       value:
-        name: byok_key_name
-        type: BYOK
+        name: hyok_example_key
+        type: HYOK
         keyConfigurationID: 12345678-90ab-cdef-1234-567890abcdef
-        description: This key is used for DB key store encryption.
-        algorithm: AES256
+        description: HYOK key connected to customer AWS KMS
+        nativeID: arn:aws:kms:us-east-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab
         provider: AWS
-        region: eu-central-1
+        accessDetails:
+          management:
+            accessAccountID: "111122223333"
+            accessUserID: "arn:aws:iam::111122223333:user/cmk-service"
+            endpoint: "https://kms.us-east-2.amazonaws.com"
+          crypto:
+            us-east-2:
+              accessAccountID: "111122223333"
+              accessUserID: "arn:aws:iam::111122223333:user/cmk-crypto"
+              endpoint: "https://kms.us-east-2.amazonaws.com"
     SystemPatchUpdatingLink:
       value:
         keyConfigurationID: 12345678-90ab-cdef-1234-567890abcdef
         retry: false
+    BYOKKeyResponse:
+      summary: BYOK key creation response
+      description: |
+        Response after creating a BYOK key. Key is in PENDING_IMPORT state until key material is imported.
+      value:
+        id: 98765432-10fe-dcba-9876-543210fedcba
+        name: byok_example_key
+        type: BYOK
+        keyConfigurationID: 12345678-90ab-cdef-1234-567890abcdef
+        description: BYOK key for database encryption
+        algorithm: AES256
+        region: eu-central-1
+        isPrimary: false
+        enabled: false
+        state: PENDING_IMPORT
+        underWorkflow: false
+        metadata:
+          createdAt: "2026-07-31T10:30:00Z"
+          updatedAt: "2026-07-31T10:30:00Z"
+    HYOKKeyResponse:
+      summary: HYOK key creation response
+      description: |
+        Response after registering a HYOK key. Key is ENABLED if successfully connected to customer keystore.
+      value:
+        id: 98765432-10fe-dcba-9876-543210fedcba
+        name: hyok_example_key
+        type: HYOK
+        keyConfigurationID: 12345678-90ab-cdef-1234-567890abcdef
+        description: HYOK key connected to customer AWS KMS
+        algorithm: AES256
+        provider: AWS
+        isPrimary: false
+        enabled: true
+        nativeID: arn:aws:kms:us-east-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab
+        state: ENABLED
+        region: eu-central-1
+        underWorkflow: false
+        accessDetails:
+          management:
+            accessAccountID: "111122223333"
+            accessUserID: "arn:aws:iam::111122223333:user/cmk-service"
+            endpoint: "https://kms.us-east-2.amazonaws.com"
+          crypto:
+            us-east-2:
+              accessAccountID: "111122223333"
+              accessUserID: "arn:aws:iam::111122223333:user/cmk-crypto"
+              endpoint: "https://kms.us-east-2.amazonaws.com"
+              isEditable: false
+        metadata:
+          createdAt: "2026-07-31T10:30:00Z"
+          updatedAt: "2026-07-31T10:30:00Z"
+          totalVersions: 1
+          primaryVersion: 1