elasticsearch/x-pack/docs/en/rest-api/security/enroll-node.asciidoc

[[security-api-node-enrollment]]
=== Enroll Node API
++++
<titleabbrev>Enroll Node</titleabbrev>
++++

Allows a new node to join an existing cluster with security features enabled.

[[security-api-node-enrollment-api-request]]
==== {api-request-title}

`GET /_security/enroll_node`

[[security-api-node-enrollment-api-prereqs]]
==== {api-prereq-title}

* You must have the `enroll` <<privileges-list-cluster,cluster privilege>> to use this API.

[[security-api-node-enrollment-api-desc]]
==== {api-description-title}

The purpose of the enroll node API is to allow a new node to join an existing cluster
where security is enabled. The enroll node API response contains all the necessary information
for the joining node to bootstrap discovery and security related settings so that it
can successfully join the cluster.

NOTE: The response contains key and certificate material that allows the
caller to generate valid signed certificates for the HTTP layer of all nodes in the cluster.

[[security-api-node-enrollment-api-examples]]
==== {api-examples-title}

[source,console]
--------------------------------------------------
GET /security/enroll_node
--------------------------------------------------
// TEST[skip:Determine behavior for keystore with multiple keys]
The API returns a response such as

[source,console-result]
--------------------------------------------------
{
  "http_ca_key" : "MIIJlAIBAzCCCVoGCSqGSIb3DQEHAaCCCUsEgglHMIIJQzCCA98GCSqGSIb3DQ....vsDfsA3UZBAjEPfhubpQysAICCAA=", <1>
  "http_ca_cert" : "MIIJlAIBAzCCCVoGCSqGSIb3DQEHAaCCCUsEgglHMIIJQzCCA98GCSqGSIb3DQ....vsDfsA3UZBAjEPfhubpQysAICCAA=", <2>
  "transport_key" : "MIIEJgIBAzCCA98GCSqGSIb3DQEHAaCCA9AEggPMMIIDyDCCA8QGCSqGSIb3....YuEiOXvqZ6jxuVSQ0CAwGGoA==", <3>
  "transport_cert" : "MIIEJgIBAzCCA98GCSqGSIb3DQEHAaCCA9AEggPMMIIDyDCCA8QGCSqGSIb3....YuEiOXvqZ6jxuVSQ0CAwGGoA==", <4>
  "cluster_name" : "cluster-name",               <5>
  "nodes_addresses" : [                          <6>
    "192.168.1.2:9300"
  ]
}
--------------------------------------------------
<1> The CA private key that can be used by the new node in order to sign its certificate
    for the HTTP layer, as a Base64 encoded string of the ASN.1 DER encoding of the key.
<2> The CA certificate that can be used by the new node in order to sign its certificate
    for the HTTP layer, as a Base64 encoded string of the ASN.1 DER encoding of the certificate.
<3> The private key that the node can use for  TLS for its transport layer, as a Base64 encoded
    string of the ASN.1 DER encoding of the key.
<4> The certificate that the node can use for  TLS for its transport layer, as a Base64 encoded
    string of the ASN.1 DER encoding of the certificate.
<5> The name of the cluster the new node is joining
<6> A list of transport addresses in the form of `host:port` for the nodes that are already
    members of the cluster.