Grant an API key

POST /_security/api_key/grant

Create an API key on behalf of another user. This API is similar to the create API keys API, however it creates the API key for a user that is different than the user that runs the API. The caller must have authentication credentials for the user on whose behalf the API key will be created. It is not possible to use this API to create an API key without that user's credentials. The supported user authentication credential types are:

username and password
Elasticsearch access tokens
JWTs

The user, for whom the authentication credentials is provided, can optionally "run as" (impersonate) another user. In this case, the API key will be created on behalf of the impersonated user.

This API is intended be used by applications that need to create and manage API keys for end users, but cannot guarantee that those users have permission to create API keys on their own behalf. The API keys are created by the Elasticsearch API key service, which is automatically enabled.

A successful grant API key API call returns a JSON structure that contains the API key, its unique id, and its name. If applicable, it also returns expiration information for the API key in milliseconds.

By default, API keys never expire. You can specify expiration information when you create the API keys.

Required authorization

Authentication

Api key

Authorization: <value>

Elasticsearch APIs support key-based authentication. You must create an API key and use the encoded value in the request header. For example:

		curl -X GET "${ES_URL}/_cat/indices?v=true" \
  -H "Authorization: ApiKey ${API_KEY}"

To get API keys, use the /_security/api_key APIs.

Basic

Authorization: Basic <credentials>

Bearer

Authorization: Bearer <token>

Elasticsearch APIs support the use of bearer tokens in the Authorization HTTP header to authenticate with the API. For examples, refer to Token-based authentication services

Query parameters

Request body

Response

application/json

Examples

Request Console 1 / 8 languages

Run POST /_security/api_key/grant to create an API key on behalf of the test_admin user.

Console Kibana Dev Tools

POST /_security/api_key/grant
{
  "grant_type": "password",
  "username" : "test_admin",
  "password" : "x-pack-test-password",
  "api_key" : {
    "name": "my-api-key",
    "expiration": "1d",
    "role_descriptors": {
      "role-a": {
        "cluster": ["all"],
        "indices": [
          {
          "names": ["index-a*"],
          "privileges": ["read"]
          }
        ]
      },
      "role-b": {
        "cluster": ["all"],
        "indices": [
          {
          "names": ["index-b*"],
          "privileges": ["all"]
          }
        ]
      }
    },
    "metadata": {
      "application": "my-application",
      "environment": {
        "level": 1,
        "trusted": true,
        "tags": ["dev", "staging"]
      }
    }
  }
}

JavaScript Elasticsearch JavaScript Client

const response = await client.security.grantApiKey({
  grant_type: "password",
  username: "test_admin",
  password: "x-pack-test-password",
  api_key: {
    name: "my-api-key",
    expiration: "1d",
    role_descriptors: {
      "role-a": {
        cluster: ["all"],
        indices: [
          {
            names: ["index-a*"],
            privileges: ["read"],
          },
        ],
      },
      "role-b": {
        cluster: ["all"],
        indices: [
          {
            names: ["index-b*"],
            privileges: ["all"],
          },
        ],
      },
    },
    metadata: {
      application: "my-application",
      environment: {
        level: 1,
        trusted: true,
        tags: ["dev", "staging"],
      },
    },
  },
});

Python Elasticsearch Python Client

resp = client.security.grant_api_key(
    grant_type="password",
    username="test_admin",
    password="x-pack-test-password",
    api_key={
        "name": "my-api-key",
        "expiration": "1d",
        "role_descriptors": {
            "role-a": {
                "cluster": [
                    "all"
                ],
                "indices": [
                    {
                        "names": [
                            "index-a*"
                        ],
                        "privileges": [
                            "read"
                        ]
                    }
                ]
            },
            "role-b": {
                "cluster": [
                    "all"
                ],
                "indices": [
                    {
                        "names": [
                            "index-b*"
                        ],
                        "privileges": [
                            "all"
                        ]
                    }
                ]
            }
        },
        "metadata": {
            "application": "my-application",
            "environment": {
                "level": 1,
                "trusted": True,
                "tags": [
                    "dev",
                    "staging"
                ]
            }
        }
    },
)

curl Shell

curl -X POST "$ELASTICSEARCH_URL/_security/api_key/grant" \
  -H "Authorization: ApiKey $ELASTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "password",
    "username": "test_admin",
    "password": "x-pack-test-password",
    "api_key": {
      "name": "my-api-key",
      "expiration": "1d",
      "role_descriptors": {
        "role-a": {
          "cluster": [
            "all"
          ],
          "indices": [
            {
              "names": [
                "index-a*"
              ],
              "privileges": [
                "read"
              ]
            }
          ]
        },
        "role-b": {
          "cluster": [
            "all"
          ],
          "indices": [
            {
              "names": [
                "index-b*"
              ],
              "privileges": [
                "all"
              ]
            }
          ]
        }
      },
      "metadata": {
        "application": "my-application",
        "environment": {
          "level": 1,
          "trusted": true,
          "tags": [
            "dev",
            "staging"
          ]
        }
      }
    }
  }'

Java Elasticsearch Java Client

client.security().grantApiKey(g -> g
    .apiKey(a -> a
        .name("my-api-key")
        .expiration(e -> e
            .time("1d")
        )
        .roleDescriptors(Map.of("role-b", RoleDescriptor.roleDescriptorOf(r -> r
                .cluster("all")
                .indices(i -> i
                    .names("index-b*")
                    .privileges("all")
                )
            ),"role-a", RoleDescriptor.roleDescriptorOf(r -> r
                .cluster("all")
                .indices(i -> i
                    .names("index-a*")
                    .privileges("read")
                )
            )))
        .metadata(Map.of("environment", JsonData.fromJson("""
{"level":1,"trusted":true,"tags":["dev","staging"]}
"""),"application", JsonData.fromJson("\"my-application\"")))
    )
    .grantType(ApiKeyGrantType.Password)
    .password("x-pack-test-password")
    .username("test_admin")
);

C# Elasticsearch .NET Client

var response = await client.Security
    .GrantApiKeyAsync(d1 => d1
        .ApiKey(d2 => d2
            .Expiration("1d")
            .Metadata(new Dictionary<string, object>()
            {
                { "application", "my-application" },
                { "environment", JsonSerializer.Deserialize<JsonElement>("""
                {
                  "level": 1,
                  "trusted": true,
                  "tags": [
                    "dev",
                    "staging"
                  ]
                }
                """) }
            })
            .Name("my-api-key")
            .RoleDescriptors([new Dictionary<string, RoleDescriptor>()
            {
                { "role-a", new()
                {
                    Cluster = [ClusterPrivilege.All],
                    Indices = [new()
                    {
                        Names = ["index-a*"],
                        Privileges = [IndexPrivilege.Read]
                    }]
                } },
                { "role-b", new()
                {
                    Cluster = [ClusterPrivilege.All],
                    Indices = [new()
                    {
                        Names = ["index-b*"],
                        Privileges = [IndexPrivilege.All]
                    }]
                } }
            }])
        )
        .GrantType(ApiKeyGrantType.Password)
        .Password("x-pack-test-password")
        .Username("test_admin")
    );

PHP Elasticsearch PHP Client

$resp = $client->security()->grantApiKey([
    "body" => [
        "grant_type" => "password",
        "username" => "test_admin",
        "password" => "x-pack-test-password",
        "api_key" => [
            "name" => "my-api-key",
            "expiration" => "1d",
            "role_descriptors" => [
                "role-a" => [
                    "cluster" => array(
                        "all",
                    ),
                    "indices" => array(
                        [
                            "names" => array(
                                "index-a*",
                            ),
                            "privileges" => array(
                                "read",
                            ),
                        ],
                    ),
                ],
                "role-b" => [
                    "cluster" => array(
                        "all",
                    ),
                    "indices" => array(
                        [
                            "names" => array(
                                "index-b*",
                            ),
                            "privileges" => array(
                                "all",
                            ),
                        ],
                    ),
                ],
            ],
            "metadata" => [
                "application" => "my-application",
                "environment" => [
                    "level" => 1,
                    "trusted" => true,
                    "tags" => array(
                        "dev",
                        "staging",
                    ),
                ],
            ],
        ],
    ],
]);

Ruby Elasticsearch Ruby Client

response = client.security.grant_api_key(
  body: {
    "grant_type": "password",
    "username": "test_admin",
    "password": "x-pack-test-password",
    "api_key": {
      "name": "my-api-key",
      "expiration": "1d",
      "role_descriptors": {
        "role-a": {
          "cluster": [
            "all"
          ],
          "indices": [
            {
              "names": [
                "index-a*"
              ],
              "privileges": [
                "read"
              ]
            }
          ]
        },
        "role-b": {
          "cluster": [
            "all"
          ],
          "indices": [
            {
              "names": [
                "index-b*"
              ],
              "privileges": [
                "all"
              ]
            }
          ]
        }
      },
      "metadata": {
        "application": "my-application",
        "environment": {
          "level": 1,
          "trusted": true,
          "tags": [
            "dev",
            "staging"
          ]
        }
      }
    }
  }
)

Response

No example

Request Console 1 / 2 languages

Run POST /_security/api_key/grant. The user (test_admin) whose credentials are provided can "run as" another user (test_user). The API key will be granted to the impersonated user (test_user).

Console Kibana Dev Tools

POST /_security/api_key/grant
{
  "grant_type": "password",
  "username" : "test_admin",  
  "password" : "x-pack-test-password",  
  "run_as": "test_user",  
  "api_key" : {
    "name": "another-api-key"
  }
}

Generated from the API spec

curl Shell

curl -X POST "$ELASTICSEARCH_URL/_security/api_key/grant" \
  -H "Authorization: ApiKey $ELASTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "password",
    "username" : "test_admin",  
    "password" : "x-pack-test-password",  
    "run_as": "test_user",  
    "api_key" : {
      "name": "another-api-key"
    }
  }'

Generated from the API spec

Response

No example