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
- service account tokens of user-managed service accounts
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.
Run as is not supported with the _user_managed_service_account grant type.
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
- Cluster privileges:
grant_api_key
Query parameters
-
If 'true', Elasticsearch refreshes the affected shards to make this operation visible to search. If 'wait_for', it waits for a refresh to make this operation visible to search. If 'false', nothing is done with refreshes.
Default value is
false.
Body
Required
-
The API key.
-
The type of grant. Supported grant types are:
access_token,password, and_user_managed_service_account.Supported values include:
access_tokenpassword_user_managed_service_account: In this type of grant, you must supply a service account token of a user-managed service account in theservice_account_tokenparameter. The API key is owned by the service account and is limited by the roles assigned to it. The service account token is authenticated on every grant, so a disabled account or an invalidated token is rejected. Tokens that belong to built-in (elastic/*) service accounts are rejected.
Values are
access_token,password, or_user_managed_service_account. -
The user's access token. If you specify the
access_tokengrant type, this parameter is required. It is not valid with other grant types. -
The client authentication for a JWT that requires it, which is what is normally sent in the
ES-Client-Authenticationrequest header. It is valid only with theaccess_tokengrant type, when the access token is a JWT. -
The service account token of a user-managed service account, as returned by the create service account token API. If you specify the
_user_managed_service_accountgrant type, this parameter is required. It is not valid with other grant types. -
The user name that identifies the user. If you specify the
passwordgrant type, this parameter is required. It is not valid with other grant types. -
The user's password. If you specify the
passwordgrant type, this parameter is required. It is not valid with other grant types. -
The name of the user to be impersonated. It is not valid with the
_user_managed_service_accountgrant type.
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"]
}
}
}
}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"
]
}
}
},
)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"],
},
},
},
});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"
]
}
}
}
}
)$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",
),
],
],
],
],
]);curl -X POST -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"]}}}}' "$ELASTICSEARCH_URL/_security/api_key/grant"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")
);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")
);
{
"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"]
}
}
}
}{
"grant_type": "password",
"username" : "test_admin",
"password" : "x-pack-test-password",
"run_as": "test_user",
"api_key" : {
"name": "another-api-key"
}
}{
"grant_type": "_user_managed_service_account",
"service_account_token": "AAEAAWFwcHMvd29ya2VyL3Rva2VuLTE6cjVXYVYzYmFMU19pT0V4UW9FTkg3UQ",
"api_key": {
"name": "worker-key",
"expiration": "1d"
}
}