Create an APM agent key

POST /api/apm/agent_keys

Spaces method and path for this operation:

post /s/{space_id}/api/apm/agent_keys

Refer to Spaces for more information.

Create a new agent key for APM. The user creating an APM agent API key must have at least the manage_own_api_key cluster privilege and the APM application-level privileges that it wishes to grant. After it is created, you can copy the API key (Base64 encoded) and use it to to authorize requests from APM agents to the APM Server.

Headers

elastic-api-version string Required

The version of the API to use

Value is 2023-10-31. Default value is 2023-10-31.
kbn-xsrf string Required

A required header to protect against CSRF attacks

application/json

Body Required

name string Required

The name of the APM agent key.
privileges array[string] Required
The APM agent key privileges. It can take one or more of the following values:
- event:write, which is required for ingesting APM agent events. * config_agent:read, which is required for APM agents to read agent configuration remotely.
Values are event:write or config_agent:read.

Responses

200 application/json

Agent key created successfully
Hide response attribute Show response attribute object
- agentKey object
  
  Agent key
  
  Hide agentKey attributes Show agentKey attributes object
  
  api_key string Required
  
  encoded string Required
  
  expiration integer(int64)
  
  id string Required
  
  name string Required
400 application/json

Bad Request response
Hide response attributes Show response attributes object
- error string
  
  Error type
- message string
  
  Error message
- statusCode number
  
  Error status code
401 application/json

Unauthorized response
Hide response attributes Show response attributes object
- error string
  
  Error type
- message string
  
  Error message
- statusCode number
  
  Error status code
403 application/json

Forbidden response
Hide response attributes Show response attributes object
- error string
  
  Error type
- message string
  
  Error message
- statusCode number
  
  Error status code
500 application/json

Internal Server Error response
Hide response attributes Show response attributes object
- error string
  
  Error type
- message string
  
  Error message
- statusCode number
  
  Error status code

POST /api/apm/agent_keys

curl \
 --request POST 'https://<KIBANA_URL>/api/apm/agent_keys' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --header "elastic-api-version: 2023-10-31" \
 --header "kbn-xsrf: true" \
 --data '{"name":"apm-key","privileges":["event:write","config_agent:read"]}'

Request example

Run `POST /api/apm/agent_keys` to create an APM agent API key with the specified privileges.

{
  "name": "apm-key",
  "privileges": [
    "event:write",
    "config_agent:read"
  ]
}

Response examples (200)

An example of a successful response from `POST /api/apm/agent_keys`, which creates an APM agent API key.

{
  "agentKey": {
    "api_key": "PjGloCGOTzaZr8ilUPvkjA",
    "encoded": "M0RDTG1uMEIzWk1oTFVhN1dCRzk6UGpHbG9DR09UemFacjhpbFVQdmtqQQ==",
    "id": "3DCLmn0B3ZMhLUa7WBG9",
    "name": "apm-key"
  }
}

Response examples (400)

An example of a 400 Bad Request response, returned when the request payload or query parameters fail validation.

{
  "error": "Bad Request",
  "message": "[request body]: expected value of type [string] but got [undefined]",
  "statusCode": 400
}

Response examples (401)

An example of a 401 Unauthorized response, returned when the request is missing valid authentication credentials.

{
  "error": "Unauthorized",
  "message": "[security_exception]: missing authentication credentials for REST request",
  "statusCode": 401
}

Response examples (403)

An example of a 403 Forbidden response, returned when the authenticated user lacks the required APM and User Experience privileges.

{
  "error": "Forbidden",
  "message": "Insufficient privileges to perform this action. The APM and User Experience feature requires `all` privileges.",
  "statusCode": 403
}

Response examples (500)

An example of a 500 Internal Server Error response, returned when an unexpected error occurs while processing the request.

{
  "error": "Internal Server Error",
  "message": "An internal server error occurred. Check the Kibana server logs for details.",
  "statusCode": 500
}