[Fleet] Improve enrollment API keys OpenAPI spec (#191585)

## Summary Closes #155550 Relates #190402 Users have reported unclear expectations from [Fleet Enrollment API Keys API](https://www.elastic.co/guide/en/fleet/current/fleet-apis.html#EnrollmentAPIKeys). These include: - Enrollment token names must be unique (impacts token creation). - Deleting an enrollment token doesn't actually delete, it revokes (invalidates it, marks it as inactive). - Revoked tokens are still returned (with `"active": false`) by `GET /api/fleet/enrollment_api_keys`. - It's not clear what happens to the API key after it's been invalidated. This PR adds some details to the OpenAPI spec. I believe, however, that some improvements could also be brought to the documentation itself in order to fully address the above concerns. The [Fleet enrollment tokens](https://www.elastic.co/guide/en/fleet/8.15/fleet-enrollment-tokens.html) doc page already describes enrollment token creation and deletion, perhaps the following information could be added: - Why the token name must be unique. - Add an explanation around revoking tokens (marked as inactive, will be removed after expiration) with a link to the [retention period setting in Elasticsearch](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-settings.html#api-key-service-settings-delete-retention-period). - A mention that inactive tokens are still returned by the GET API and visible in the UI until they are cleaned up. A final note around the variations in terminology (not a big issue, I think): - "enrollment tokens" in the docs vs. "enrollment API keys" in the OpenAPI spec (I thought it would be best to keep the latter consistent) - "[revoke token](https://www.elastic.co/guide/en/fleet/8.15/fleet-enrollment-tokens.html#revoke-fleet-enrollment-tokens)" vs. "[invalidate API key](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-invalidate-api-key.html)" --------- Co-authored-by: Elastic Machine <[email protected]>
elastic · Aug 29, 2024 · 230d274 · 230d274
1 parent 9babac0
commit 230d274
Show file tree

Hide file tree

Showing 5 changed files with 97 additions and 12 deletions.
diff --git a/x-pack/plugins/fleet/common/openapi/bundled.json b/x-pack/plugins/fleet/common/openapi/bundled.json
@@ -4112,6 +4112,17 @@
         "tags": [
           "Fleet enrollment API keys"
         ],
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/page_size"
+          },
+          {
+            "$ref": "#/components/parameters/page_index"
+          },
+          {
+            "$ref": "#/components/parameters/kuery"
+          }
+        ],
         "responses": {
           "200": {
             "description": "OK",
@@ -4157,8 +4168,7 @@
             "$ref": "#/components/responses/error"
           }
         },
-        "operationId": "get-enrollment-api-keys",
-        "parameters": []
+        "operationId": "get-enrollment-api-keys"
       },
       "post": {
         "summary": "Create enrollment API key",
@@ -4191,6 +4201,28 @@
             "$ref": "#/components/responses/error"
           }
         },
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "name": {
+                    "type": "string",
+                    "description": "The name of the enrollment API key. Must be unique."
+                  },
+                  "policy_id": {
+                    "type": "string",
+                    "description": "The ID of the agent policy the Elastic Agent will be enrolled in."
+                  }
+                },
+                "required": [
+                  "policy_id"
+                ]
+              }
+            }
+          }
+        },
         "operationId": "create-enrollment-api-keys",
         "parameters": [
           {
@@ -4241,7 +4273,7 @@
         "operationId": "get-enrollment-api-key"
       },
       "delete": {
-        "summary": "Delete enrollment API key by ID",
+        "summary": "Revoke enrollment API key by ID by marking it as inactive",
         "tags": [
           "Fleet enrollment API keys"
         ],
@@ -8199,19 +8231,24 @@
             "type": "string"
           },
           "api_key_id": {
-            "type": "string"
+            "type": "string",
+            "description": "The ID of the API key in the Security API."
           },
           "api_key": {
-            "type": "string"
+            "type": "string",
+            "description": "The enrollment API key (token) used for enrolling Elastic Agents."
           },
           "name": {
-            "type": "string"
+            "type": "string",
+            "description": "The name of the enrollment API key."
           },
           "active": {
-            "type": "boolean"
+            "type": "boolean",
+            "description": "When false, the enrollment API key is revoked and cannot be used for enrolling Elastic Agents."
           },
           "policy_id": {
-            "type": "string"
+            "type": "string",
+            "description": "The ID of the agent policy the Elastic Agent will be enrolled in."
           },
           "created_at": {
             "type": "string"

diff --git a/x-pack/plugins/fleet/common/openapi/bundled.yaml b/x-pack/plugins/fleet/common/openapi/bundled.yaml
@@ -2561,6 +2561,10 @@ paths:
       summary: List enrollment API keys
       tags:
         - Fleet enrollment API keys
+      parameters:
+        - $ref: '#/components/parameters/page_size'
+        - $ref: '#/components/parameters/page_index'
+        - $ref: '#/components/parameters/kuery'
       responses:
         '200':
           description: OK
@@ -2592,7 +2596,6 @@ paths:
         '400':
           $ref: '#/components/responses/error'
       operationId: get-enrollment-api-keys
-      parameters: []
     post:
       summary: Create enrollment API key
       tags:
@@ -2613,6 +2616,22 @@ paths:
                       - created
         '400':
           $ref: '#/components/responses/error'
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                name:
+                  type: string
+                  description: The name of the enrollment API key. Must be unique.
+                policy_id:
+                  type: string
+                  description: >-
+                    The ID of the agent policy the Elastic Agent will be
+                    enrolled in.
+              required:
+                - policy_id
       operationId: create-enrollment-api-keys
       parameters:
         - $ref: '#/components/parameters/kbn_xsrf'
@@ -2643,7 +2662,7 @@ paths:
           $ref: '#/components/responses/error'
       operationId: get-enrollment-api-key
     delete:
-      summary: Delete enrollment API key by ID
+      summary: Revoke enrollment API key by ID by marking it as inactive
       tags:
         - Fleet enrollment API keys
       responses:
@@ -5279,14 +5298,21 @@ components:
           type: string
         api_key_id:
           type: string
+          description: The ID of the API key in the Security API.
         api_key:
           type: string
+          description: The enrollment API key (token) used for enrolling Elastic Agents.
         name:
           type: string
+          description: The name of the enrollment API key.
         active:
           type: boolean
+          description: >-
+            When false, the enrollment API key is revoked and cannot be used for
+            enrolling Elastic Agents.
         policy_id:
           type: string
+          description: The ID of the agent policy the Elastic Agent will be enrolled in.
         created_at:
           type: string
       required:

diff --git a/x-pack/plugins/fleet/common/openapi/components/schemas/enrollment_api_key.yaml b/x-pack/plugins/fleet/common/openapi/components/schemas/enrollment_api_key.yaml
@@ -5,14 +5,19 @@ properties:
     type: string
   api_key_id:
     type: string
+    description: The ID of the API key in the Security API.
   api_key:
     type: string
+    description: The enrollment API key (token) used for enrolling Elastic Agents.
   name:
     type: string
+    description: The name of the enrollment API key.
   active:
     type: boolean
+    description: When false, the enrollment API key is revoked and cannot be used for enrolling Elastic Agents.
   policy_id:
     type: string
+    description: The ID of the agent policy the Elastic Agent will be enrolled in.
   created_at:
     type: string
 required:

diff --git a/x-pack/plugins/fleet/common/openapi/paths/enrollment_api_keys.yaml b/x-pack/plugins/fleet/common/openapi/paths/enrollment_api_keys.yaml
@@ -2,6 +2,10 @@ get:
   summary: List enrollment API keys
   tags:
     - Fleet enrollment API keys
+  parameters:
+    - $ref: ../components/parameters/page_size.yaml
+    - $ref: ../components/parameters/page_index.yaml
+    - $ref: ../components/parameters/kuery.yaml
   responses:
     '200':
       description: OK
@@ -33,7 +37,6 @@ get:
     '400':
       $ref: ../components/responses/error.yaml
   operationId: get-enrollment-api-keys
-  parameters: []
 post:
   summary: Create enrollment API key
   tags:
@@ -54,6 +57,20 @@ post:
                   - created
     '400':
       $ref: ../components/responses/error.yaml
+  requestBody:
+    content:
+      application/json:
+        schema:
+          type: object
+          properties:
+            name:
+              type: string
+              description: The name of the enrollment API key. Must be unique.
+            policy_id:
+              type: string
+              description: The ID of the agent policy the Elastic Agent will be enrolled in.
+          required:
+            - policy_id
   operationId: create-enrollment-api-keys
   parameters:
     - $ref: ../components/headers/kbn_xsrf.yaml
diff --git a/x-pack/plugins/fleet/common/openapi/paths/enrollment_api_keys@{key_id}.yaml b/x-pack/plugins/fleet/common/openapi/paths/enrollment_api_keys@{key_id}.yaml
@@ -24,7 +24,7 @@ get:
       $ref: ../components/responses/error.yaml
   operationId: get-enrollment-api-key
 delete:
-  summary: Delete enrollment API key by ID
+  summary: Revoke enrollment API key by ID by marking it as inactive
   tags:
     - Fleet enrollment API keys
   responses: