Dipping a toe into platform automation: Generate a roles token

When you install Elastic Cloud Enterprise on additional hosts, you must specify a valid roles token. This requirement is a security feature designed to prevent unauthorized hosts from joining your ECE installation. In this example, we show how you can generate a roles token for allocators and use it to install ECE on an additional host.

Before you begin

To make it easier to use roles tokens, you automatically get several tokens after installation on the first host. If you revoke these tokens or no longer have access to them, you can use the RESTful API to generate a new token. With the new token, you can install ECE on additional hosts and add the right roles at the same time.

Additional documentation for roles tokens is available, including information on generating ephemeral tokens that expire after a set period. To learn more about how the process works, see Generate Roles Tokens.


To generate a roles token:

  1. Create a persistent token that can be used to assign the allocator role to hosts you install ECE on:

    curl -k -H 'Content-Type: application/json' -u $USER:$PASSWORD https://$COORDINATOR_HOST:12443/api/v1/platform/configuration/security/enrollment-tokens -d '{ "persistent": true, "roles": [ "allocator"] }'
      "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiI3YTRkYjVhMC1kMDViLTQzZjctODRhMy1jZGRiODFmNTI1NGYiLCJyb2xlcyI6WyJhbGxvY2F0b3IiXSwiaXNzIjoiY3VycmVudCIsInBlcnNpc3RlbnQiOnRydWV9.L4jb_2U26IjvxLtVjlYYAjCZDrokd14o9dFOb--9wlQ",
      "token_id": "7a4db5a0-d05b-43f7-84a3-cddb81f5254f"

    A user with sufficient privileges, such as the admin user

    The password for the user

    A host that you installed Elastic Cloud Enterprise on that holds the coordinator role

    You are shown the new generated token only once, so make sure you keep it somewhere safe.

  2. When installing ECE on the additional host, include the token and specify the allocator role:

    bash elastic-cloud-enterprise.sh install --coordinator-host COORDINATOR_HOST --roles-token 'ROLES_TOKEN' --roles "allocator"

    The roles token you generated in Step 1

  3. After installation completes, you can use the new host’s IP address, here, to verify through the RESTful API that the new allocator is available (some output was omitted for brevity):

    curl -k -X GET -u $USER:$PASSWORD https://$COORDINATOR_HOST:12443/api/v1/platform/infrastructure/allocators
      "zones": [{
        "zone_id": "ece-region-1b",
        "allocators": [{
          "public_hostname": "",
          "instances": [],
          "status": {
            "connected": true
          "host_ip": "",
          "allocator_id": "",
          "capacity": {
            "memory": {
              "total": 12398,
              "used": 0

    Alternatively, you can also check in the Cloud UI that the new allocator is available.