---
type: api
title: Create an APM agent key
description: **Spaces method and path for this operation:**
url: https://www.elastic.co/elastic/docs-builder/docs/4371/api/doc/kibana/v9/operation/operation-createagentkey
resource: https://www.elastic.co/elastic/docs-builder/docs/4371/api/doc/kibana/v9/operation/operation-createagentkey
products:
  - Kibana
---

# Create an APM agent key

- Server: `https://{kibana_url}`

## Paths

- `POST` `/api/apm/agent_keys`
- `POST` `/s/{space_id}/api/apm/agent_keys`

- [Api key auth](/elastic/docs-builder/docs/4371/api/doc/kibana/v9/authentication#apikeyauth)
- [Basic auth](/elastic/docs-builder/docs/4371/api/doc/kibana/v9/authentication#basicauth)

## Description

Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-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.

## Request Body

`application/json`

- `name` (string) — required
  The name of the APM agent key.
- `privileges` ([] enum) — 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: `event:write`, `config_agent:read`

## Responses

#### `200`

Agent key created successfully

`application/json`

- `agentKey` (object)
  Agent key
  - `api_key` (string)
  - `encoded` (string)
  - `expiration` (integer)
  - `id` (string)
  - `name` (string)
#### `400`

Bad Request response

`application/json`

- `error` (string)
  Error type
- `message` (string)
  Error message
- `statusCode` (number)
  Error status code
#### `401`

Unauthorized response

`application/json`

- `error` (string)
  Error type
- `message` (string)
  Error message
- `statusCode` (number)
  Error status code
#### `403`

Forbidden response

`application/json`

- `error` (string)
  Error type
- `message` (string)
  Error message
- `statusCode` (number)
  Error status code
#### `500`

Internal Server Error response

`application/json`

- `error` (string)
  Error type
- `message` (string)
  Error message
- `statusCode` (number)
  Error status code
## Code Examples

#### Console

```console
POST /api/apm/agent_keys
{
  "name": "apm-key",
  "privileges": [
    "event:write",
    "config_agent:read"
  ]
}
```

#### curl

```curl
curl -X POST "https://{kibana_url}/api/apm/agent_keys" \
  -H "elastic-api-version: string" \
  -H "kbn-xsrf: true" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "apm-key",
  "privileges": [
    "event:write",
    "config_agent:read"
  ]
}'
```

## Response Examples

#### Create agent key response1

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

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

#### Bad request

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

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

#### Unauthorized

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

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

#### Forbidden

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

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

#### Internal server error

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

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