It is time to say goodbye: This version of Elastic Cloud Enterprise has reached end-of-life (EOL) and is no longer supported.

The documentation for this version is no longer being maintained. If you are running this version, we strongly advise you to upgrade. For the latest information, see the current release documentation.

« RESTful API API calls »
Elastic Docs ›Elastic Cloud Enterprise Reference [2.12] ›RESTful API

Authentication

edit

Authentication

edit

This documentation applies to the Elastic Cloud Enterprise API only. If you are using Elasticsearch Service, check the Elastic Cloud API information instead.

The Elastic Cloud Enterprise RESTful APIs support both key-based and token-based authentication. Key-based is generally the preferred method.

Authenticate using an API key

edit

For key-based API authentication, you can create an API key through the Elastic Cloud Enterprise UI. Once created, you can specify the key in the header of your API calls to authenticate.

API keys are not available for the built-in users (admin and readonly). Therefore, the API Keys settings page on the UI does not appear for these users.

To create an API key:

  1. Sign in to the Cloud UI.
  2. Go to Profile, Settings, and then API Keys.
  3. Click Generate API key.
  4. Provide your account password.
  5. Specify a name for the API key.
  6. Copy the generated API key and store it in a safe place. You can also download the key as a CSV file.

The API key has no expiration, so it may be used indefinitely. The API key has the same permissions as the API key owner. You may have multiple API keys for different purposes and you can revoke them when you no longer need them.

Currently, API keys cannot be generated for the admin and readonly users that come pre-configured with your Elastic Cloud Enterprise installation.

To revoke an API key:

  1. Sign in to the Cloud UI.
  2. Go to Profile, Settings, and then API Keys.
  3. Click the trash icon under the Revoke column for any keys that you want to delete.

Authenticate using a bearer token

edit

For token-based API authentication, you can use the same username and password that you use to log into the Cloud UI. If you want to use the credentials that were provided when you installed Elastic Cloud Enterprise on your first host, for example admin, you can retrieve them separately.

For operations that only read information, but don’t create, update or delete, you can authenticate with a user that has restricted permissions, such as the readonly user.

To create a bearer token:

  1. Open a terminal and send your credentials to the login endpoint:

    curl -k -X POST -H 'Content-Type: application/json' https://$COORDINATOR_HOST:12443/api/v1/users/auth/_login --data-binary '
{
  "username": "USER",
  "password": "PASSWORD"
}'

    If your credentials are valid, the response from the login API will contain a JSON Web Token (JWT):

    { "token": "eyJ0eXa...<very long string>...MgBmsw4s" }
  2. Specify the bearer token in the Authentication header of your API requests. To learn more, see accessing the API from the command line.
« RESTful API API calls »