Kibana Fleet enrollment API keys API
Fleet enrollment API keys APIs enable you to manage enrollment API keys for Fleet, including creating, retrieving, and revoking API keys used for agent enrollment.
OpenAPI Specification
openapi: 3.0.3
info:
contact:
name: Kibana Team
description: 'The Kibana REST APIs enable you to manage resources such as connectors, data views, and saved objects.
The API calls are stateless.
Each request that you make happens in isolation from other calls and must include all of the necessary information for Kibana to fulfill the
request.
API requests return JSON output, which is a format that is machine-readable and works well for automation.
To interact with Kibana APIs, use the following operations:
- GET: Fetches the information.
- PATCH: Applies partial modifications to the existing information.
- POST: Adds new information.
- PUT: Updates the existing information.
- DELETE: Removes the information.
You can prepend any Kibana API endpoint with `kbn:` and run the request in **Dev Tools → Console**.
For example:
```
GET kbn:/api/data_views
```
For more information about the console, refer to [Run API requests](https://www.elastic.co/docs/explore-analyze/query-filter/tools/console).
NOTE: Access to internal Kibana API endpoints will be restricted in Kibana version 9.0. Please move any integrations to publicly documented APIs.
## Documentation source and versions
This documentation is derived from the `main` branch of the [kibana](https://github.com/elastic/kibana) repository.
It is provided under license [Attribution-NonCommercial-NoDerivatives 4.0 International](https://creativecommons.org/licenses/by-nc-nd/4.0/).
This documentation contains work-in-progress information for future Elastic Stack releases.
'
title: Kibana APIs Actions Fleet enrollment API keys API
version: ''
x-doc-license:
name: Attribution-NonCommercial-NoDerivatives 4.0 International
url: https://creativecommons.org/licenses/by-nc-nd/4.0/
x-feedbackLink:
label: Feedback
url: https://github.com/elastic/docs-content/issues/new?assignees=&labels=feedback%2Ccommunity&projects=&template=api-feedback.yaml&title=%5BFeedback%5D%3A+
servers:
- url: https://{kibana_url}
variables:
kibana_url:
default: localhost:5601
security:
- apiKeyAuth: []
- basicAuth: []
tags:
- name: Fleet enrollment API keys
description: 'Fleet enrollment API keys APIs enable you to manage enrollment API keys for Fleet, including creating, retrieving, and revoking API keys used for agent enrollment.
'
x-displayName: Fleet enrollment API keys
paths:
/api/fleet/enrollment_api_keys:
get:
description: '**Spaces method and path for this operation:**
<div><span class="operation-verb get">get</span> <span class="operation-path">/s/{space_id}/api/fleet/enrollment_api_keys</span></div>
Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.
List all enrollment API keys.<br/><br/>[Required authorization] Route required privileges: fleet-agents-all OR fleet-setup.'
operationId: get-fleet-enrollment-api-keys
parameters:
- description: Page number
in: query
name: page
required: false
schema:
default: 1
type: number
- description: Number of results per page
in: query
name: perPage
required: false
schema:
default: 20
type: number
- description: A KQL query string to filter results
in: query
name: kuery
required: false
schema:
type: string
responses:
'200':
content:
application/json:
examples:
getEnrollmentApiKeysExample:
description: List of enrollment API keys
value:
items:
- active: true
api_key: api-key-value-1
api_key_id: api-key-id-1
created_at: '2024-01-01T00:00:00.000Z'
id: key-id-1
name: Default policy enrollment key
policy_id: policy-id-1
list:
- active: true
api_key: api-key-value-1
api_key_id: api-key-id-1
created_at: '2024-01-01T00:00:00.000Z'
id: key-id-1
name: Default policy enrollment key
policy_id: policy-id-1
page: 1
perPage: 20
total: 1
schema:
additionalProperties: false
type: object
properties:
items:
items:
additionalProperties: false
type: object
properties:
active:
description: When false, the enrollment API key is revoked and cannot be used for enrolling Elastic Agents.
type: boolean
api_key:
description: The enrollment API key (token) used for enrolling Elastic Agents.
type: string
api_key_id:
description: The ID of the API key in the Security API.
type: string
created_at:
type: string
hidden:
type: boolean
id:
type: string
name:
description: The name of the enrollment API key.
type: string
policy_id:
description: The ID of the agent policy the Elastic Agent will be enrolled in.
type: string
required:
- id
- api_key_id
- api_key
- active
- created_at
maxItems: 10000
type: array
list:
deprecated: true
items:
additionalProperties: false
type: object
properties:
active:
description: When false, the enrollment API key is revoked and cannot be used for enrolling Elastic Agents.
type: boolean
api_key:
description: The enrollment API key (token) used for enrolling Elastic Agents.
type: string
api_key_id:
description: The ID of the API key in the Security API.
type: string
created_at:
type: string
hidden:
type: boolean
id:
type: string
name:
description: The name of the enrollment API key.
type: string
policy_id:
description: The ID of the agent policy the Elastic Agent will be enrolled in.
type: string
required:
- id
- api_key_id
- api_key
- active
- created_at
maxItems: 10000
type: array
page:
type: number
perPage:
type: number
total:
type: number
required:
- items
- total
- page
- perPage
- list
description: Successful response
'400':
content:
application/json:
examples:
genericErrorResponseExample:
description: Example of a generic error response
value:
error: Bad Request
message: An error message describing what went wrong
statusCode: 400
schema:
additionalProperties: false
description: Generic Error
type: object
properties:
attributes:
nullable: true
error:
type: string
errorType:
type: string
message:
type: string
statusCode:
type: number
required:
- message
- attributes
description: Bad Request
summary: Get enrollment API keys
tags:
- Fleet enrollment API keys
x-metaTags:
- content: Kibana
name: product_name
post:
description: '**Spaces method and path for this operation:**
<div><span class="operation-verb post">post</span> <span class="operation-path">/s/{space_id}/api/fleet/enrollment_api_keys</span></div>
Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.
Create an enrollment API key for a given agent policy.<br/><br/>[Required authorization] Route required privileges: fleet-agents-all.'
operationId: post-fleet-enrollment-api-keys
parameters:
- description: A required header to protect against CSRF attacks
in: header
name: kbn-xsrf
required: true
schema:
example: 'true'
type: string
requestBody:
content:
application/json:
examples:
postEnrollmentApiKeyRequestExample:
description: Create an enrollment API key for an agent policy
value:
expiration: '2025-01-01T00:00:00.000Z'
name: My enrollment key
policy_id: policy-id-1
schema:
additionalProperties: false
type: object
properties:
expiration:
type: string
name:
type: string
policy_id:
type: string
required:
- policy_id
responses:
'200':
content:
application/json:
examples:
postEnrollmentApiKeyExample:
description: The created enrollment API key
value:
action: created
item:
active: true
api_key: api-key-value-1
api_key_id: api-key-id-1
created_at: '2024-01-01T00:00:00.000Z'
id: key-id-1
name: My enrollment key
policy_id: policy-id-1
schema:
additionalProperties: false
type: object
properties:
action:
enum:
- created
type: string
item:
additionalProperties: false
type: object
properties:
active:
description: When false, the enrollment API key is revoked and cannot be used for enrolling Elastic Agents.
type: boolean
api_key:
description: The enrollment API key (token) used for enrolling Elastic Agents.
type: string
api_key_id:
description: The ID of the API key in the Security API.
type: string
created_at:
type: string
hidden:
type: boolean
id:
type: string
name:
description: The name of the enrollment API key.
type: string
policy_id:
description: The ID of the agent policy the Elastic Agent will be enrolled in.
type: string
required:
- id
- api_key_id
- api_key
- active
- created_at
required:
- item
- action
description: Successful response
'400':
content:
application/json:
examples:
genericErrorResponseExample:
description: Example of a generic error response
value:
error: Bad Request
message: An error message describing what went wrong
statusCode: 400
schema:
additionalProperties: false
description: Generic Error
type: object
properties:
attributes:
nullable: true
error:
type: string
errorType:
type: string
message:
type: string
statusCode:
type: number
required:
- message
- attributes
description: Bad Request
summary: Create an enrollment API key
tags:
- Fleet enrollment API keys
x-metaTags:
- content: Kibana
name: product_name
/api/fleet/enrollment_api_keys/_bulk_delete:
post:
description: '**Spaces method and path for this operation:**
<div><span class="operation-verb post">post</span> <span class="operation-path">/s/{space_id}/api/fleet/enrollment_api_keys/_bulk_delete</span></div>
Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.
Revoke or delete multiple enrollment API keys.<br/><br/>[Required authorization] Route required privileges: fleet-agents-all.'
operationId: post-fleet-enrollment-api-keys-bulk-delete
parameters:
- description: A required header to protect against CSRF attacks
in: header
name: kbn-xsrf
required: true
schema:
example: 'true'
type: string
requestBody:
content:
application/json:
examples:
bulkDeleteByIdsExample:
description: Bulk delete enrollment API keys by IDs
value:
forceDelete: true
tokenIds:
- token-id-1
- token-id-2
bulkDeleteByKueryExample:
description: Bulk delete enrollment API keys by KQL query
value:
forceDelete: false
kuery: policy_id:"policy-id-1"
schema:
additionalProperties: false
type: object
properties:
forceDelete:
default: false
description: When false (default), invalidate the API key and mark the token as inactive. When true, also delete the token document.
type: boolean
includeHidden:
default: false
description: When true, allow deletion of hidden enrollment tokens (managed/agentless policies). Defaults to false.
type: boolean
kuery:
description: KQL query to select enrollment tokens to delete.
type: string
tokenIds:
description: List of enrollment token IDs to delete.
items:
type: string
maxItems: 10000
type: array
responses:
'200':
content:
application/json:
examples:
bulkDeleteEnrollmentApiKeysExample:
description: The enrollment API keys were successfully processed
value:
action: deleted
count: 2
errorCount: 0
successCount: 2
schema:
additionalProperties: false
type: object
properties:
action:
type: string
count:
type: number
errorCount:
type: number
successCount:
type: number
required:
- action
- count
- successCount
- errorCount
description: Successful response
'400':
content:
application/json:
examples:
genericErrorResponseExample:
description: Example of a generic error response
value:
error: Bad Request
message: Either tokenIds or kuery must be provided
statusCode: 400
schema:
additionalProperties: false
description: Generic Error
type: object
properties:
attributes:
nullable: true
error:
type: string
errorType:
type: string
message:
type: string
statusCode:
type: number
required:
- message
- attributes
description: Bad Request
summary: Bulk revoke or delete enrollment API keys
tags:
- Fleet enrollment API keys
x-state: Generally available; added in 9.5.0
x-metaTags:
- content: Kibana
name: product_name
/api/fleet/enrollment_api_keys/{keyId}:
delete:
description: '**Spaces method and path for this operation:**
<div><span class="operation-verb delete">delete</span> <span class="operation-path">/s/{space_id}/api/fleet/enrollment_api_keys/{keyId}</span></div>
Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.
Revoke or delete an enrollment API key by ID. Use `forceDelete=true` to remove the document.<br/><br/>[Required authorization] Route required privileges: fleet-agents-all.'
operationId: delete-fleet-enrollment-api-keys-keyid
parameters:
- description: A required header to protect against CSRF attacks
in: header
name: kbn-xsrf
required: true
schema:
example: 'true'
type: string
- description: The ID of the enrollment API key
in: path
name: keyId
required: true
schema:
type: string
- description: When false (default), invalidate the API key and mark the token as inactive. When true, also delete the token document.
in: query
name: forceDelete
required: false
schema:
default: false
type: boolean
- description: When true, allow deletion of hidden enrollment tokens (managed/agentless policies). Defaults to false.
in: query
name: includeHidden
required: false
schema:
default: false
type: boolean
responses:
'200':
content:
application/json:
examples:
deleteEnrollmentApiKeyExample:
description: The enrollment API key was successfully revoked
value:
action: deleted
schema:
additionalProperties: false
type: object
properties:
action:
enum:
- deleted
type: string
required:
- action
description: Successful response
'400':
content:
application/json:
examples:
genericErrorResponseExample:
description: Example of a generic error response
value:
error: Bad Request
message: An error message describing what went wrong
statusCode: 400
schema:
additionalProperties: false
description: Generic Error
type: object
properties:
attributes:
nullable: true
error:
type: string
errorType:
type: string
message:
type: string
statusCode:
type: number
required:
- message
- attributes
description: Bad Request
'404':
content:
application/json:
examples:
notFoundExample:
description: No enrollment API key was found with the given ID
value:
error: Not Found
message: EnrollmentAPIKey key-id-1 not found
statusCode: 404
description: Not Found
summary: Revoke or delete an enrollment API key
tags:
- Fleet enrollment API keys
x-metaTags:
- content: Kibana
name: product_name
get:
description: '**Spaces method and path for this operation:**
<div><span class="operation-verb get">get</span> <span class="operation-path">/s/{space_id}/api/fleet/enrollment_api_keys/{keyId}</span></div>
Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.
Get an enrollment API key by ID.<br/><br/>[Required authorization] Route required privileges: fleet-agents-all OR fleet-setup.'
operationId: get-fleet-enrollment-api-keys-keyid
parameters:
- description: The ID of the enrollment API key
in: path
name: keyId
required: true
schema:
type: string
responses:
'200':
content:
application/json:
examples:
getEnrollmentApiKeyExample:
description: An enrollment API key
value:
item:
active: true
api_key: api-key-value-1
api_key_id: api-key-id-1
created_at: '2024-01-01T00:00:00.000Z'
id: key-id-1
name: Default policy enrollment key
policy_id: policy-id-1
schema:
additionalProperties: false
type: object
properties:
item:
additionalProperties: false
type: object
properties:
active:
description: When false, the enrollment API key is revoked and cannot be used for enrolling Elastic Agents.
type: boolean
api_key:
description: The enrollment API key (token) used for enrolling Elastic Agents.
type: string
api_key_id:
description: The ID of the API key in the Security API.
type: string
created_at:
type: string
hidden:
type: boolean
id:
type: string
name:
description: The name of the enrollment API key.
type: string
policy_id:
description: The ID of the agent policy the Elastic Agent will be enrolled in.
type: string
required:
- id
- api_key_id
- api_key
- active
- created_at
required:
- item
description: Successful response
'400':
content:
application/json:
examples:
genericErrorResponseExample:
description: Example of a generic error response
value:
error: Bad Request
message: An error message describing what went wrong
statusCode: 400
schema:
additionalProperties: false
description: Generic Error
type: object
properties:
attributes:
nullable: true
error:
type: string
errorType:
type: string
message:
type: string
statusCode:
type: number
required:
- message
- attributes
description: Bad Request
'404':
content:
application/json:
examples:
notFoundExample:
description: No enrollment API key was found with the given ID
value:
error: Not Found
message: EnrollmentAPIKey key-id-1 not found
statusCode: 404
description: Not Found
summary: Get an enrollment API key
tags:
- Fleet enrollment API keys
x-metaTags:
- content: Kibana
name: product_name
components:
securitySchemes:
apiKeyAuth:
description: 'These APIs use key-based authentication. You must create an API key and use the encoded value in the request header. For example: `Authorization: ApiKey base64AccessApiKey`
'
in: header
name: Authorization
type: apiKey
basicAuth:
scheme: basic
type: http
x-topics:
- title: Kibana spaces
content: "Spaces enable you to organize your dashboards and other saved objects into meaningful categories.\nYou can use the default space or create your own spaces.\n\nTo run APIs in non-default spaces, you must add `s/{space_id}/` to the path.\nFor example:\n\n```bash\ncurl -X GET \"http://${KIBANA_URL}/s/marketing/api/data_views\" \\\n -H \"Authorization: ApiKey ${API_KEY}\"\n```\n\nIf you use the Kibana console to send API requests, it automatically adds the appropriate space identifier.\n\nTo learn more, check out [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces).\n"