---
title: "POST /api/fleet/agents/enroll"
method: POST
path: "/api/fleet/agents/enroll"
---

# POST /api/fleet/agents/enroll

`POST /api/fleet/agents/enroll`

Enroll a new agent to fleet-server. The agent is enrolled in the policy encoded in the apiKey used.

## Headers

- `User-Agent` string, required
- `X-Request-Id` string
- `Elastic-Api-Version` string

## Request body

- EnrollRequest — A request to enroll a new agent into fleet.
  - `type` 'PERMANENT', required — The enrollment type of the agent. The agent only supports the PERMANENT value. In the future the enrollment type may be used to indicate agents that use fleet for reporting and monitoring, but do not use policies.
  - `shared_id` string, required — The shared ID of the agent. To support pre-existing installs. Never implemented.
  - `metadata` EnrollMetadata, required — Metadata associated with the agent that is enrolling to fleet.
    - `user_provided` string, application/json, required — An embedded JSON object that holds user-provided meta-data values. Defined in fleet-server as a `json.RawMessage`. fleet-server does not use these values on enrollment of an agent. Defined in the elastic-agent as a `map[string]interface{}` with no way to specify any values.
    - `local` string, application/json, required — An embedded JSON object that holds meta-data values. Defined in fleet-server as a `json.RawMessage`, defined as an object in the elastic-agent. elastic-agent will populate the object with information from the binary and host/system environment. If not empty fleet-server will update the value of `local["elastic"]["agent"]["id"]` to the agent ID (assuming the keys exist). The (possibly updated) value is sent by fleet-server when creating the record for a new agent.
    - `tags` string[], required — User provided tags for the agent. fleet-server will pass the tags to the agent record on enrollment.

## Response `200`

Agent enrolled successfully.

- EnrollResponse — The enrollment action response.
  - `action` string, required — The action result. Will have the value "created".
  - `item` EnrollResponseItem, required — Response to a successful enrollment of an agent into fleet.
    - `id` string, required — The agent ID
    - `active` boolean, required — If the agent is active in fleet. Set to true upon enrollment. Handling of other values never implemented.
    - `policy_id` string, required — The policy ID that the agent is enrolled with. Decoded from the API key used in the request.
    - `type` string, required — The enrollment request type. Handling of other values never implemented.
    - `enrolled_at` string, required — The RFC3339 timestamp that the agent was enrolled at.
    - `user_provided_metadata` string, application/json, required — A copy of the user provided metadata from the enrollment request. Currently will be empty.
    - `local_metadata` string, application/json, required — A copy of the (updated) local metadata provided in the enrollment request. Never used by agent.
    - `actions` object[], required — Defined in fleet-server and elastic-agent as `[]interface{}`. Never used by agent.
    - `access_api_key_id` string, required — The id of the ApiKey that fleet-server has generated for the enrolling agent.
    - `access_api_key` string, password, required — The ApiKey token that fleet-server has generated for the enrolling agent.
    - `status` string, required — Agent status from fleet-server. fleet-ui may differ. Never used by agent.
    - `tags` string[], required — A copy of the tags that were sent with the enrollment request.

## Other responses

- `400` — A 400 response for receiving an invalid User-Agent, Elastic-Api-Version header or version number (checkin and enroll endpoints). In the case where an invalid or unsupported Elastic-Api-Version header is requested, the response will contain the default version number. Or any other undefined error encounted by the fleet-server. May be returned by any endpoint except /api/fleet/status.
- `401` — 401 response when the API key is not enabled on any endpoint except /api/fleet/status. Or when there are issues updating an inactive agent on the ack endpoint.
- `408` — 408 request timeout.
- `500` — A 500 response for encountering not expected bahavior.
- `503` — 503 response when the server is not available for some reason. Such as if a context is cancelled or the connection (to ES) is refused. May be returned by any endpoint.

---

[API](https://skmtc.net/elastic/apis/fleet-server-api.md) · [All operations](https://skmtc.net/elastic/apis/fleet-server-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/elastic/fleet-server-api/versions/e1c8da877dd8/schema)