Create an API key

POST also PUT /_security/api_key

Create an API key for access without requiring basic authentication.

IMPORTANT: If the credential that is used to authenticate this request is an API key, the derived API key cannot have any privileges. If you specify privileges, the API returns an error.

A successful request 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.

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

The API keys are created by the Elasticsearch API key service, which is automatically enabled. To configure or turn off the API key service, refer to API key service setting documentation.

Required authorization

Cluster privileges: manage_own_api_key

About API key service settings

Query Parameters

refresh enum Refresh: If true (the default) then refresh the affected shards to make this operation visible to search, if wait_for then wait for a refresh to make this operation visible to search, if false then do nothing with refreshes.; Values: true false wait_for

Run POST /_security/api_key to create an API key. If expiration is not provided, the API keys do not expire. If role_descriptors is not provided, the permissions of the authenticated user are applied.

Request Console 1 / 8 languages

Console Kibana Dev Tools

POST /_security/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.createApiKey({
  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.create_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" \
  -H "Authorization: ApiKey $ELASTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "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().createApiKey(c -> c
    .expiration(e -> e
        .time("1d")
    )
    .metadata(Map.of("environment", JsonData.fromJson("""
{"level":1,"trusted":true,"tags":["dev","staging"]}
"""),"application", JsonData.fromJson("\"my-application\"")))
    .name("my-api-key")
    .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")
            )
        )))
);

C# Elasticsearch .NET Client

var response = await client.Security
    .CreateApiKeyAsync(d1 => d1
        .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(d2 => d2
            .Add("role-a", d3 => d3
                .Cluster(ClusterPrivilege.All)
                .Indices(d4 => d4
                    .Names(["index-a*"])
                    .Privileges(IndexPrivilege.Read)
                )
            )
            .Add("role-b", d3 => d3
                .Cluster(ClusterPrivilege.All)
                .Indices(d4 => d4
                    .Names(["index-b*"])
                    .Privileges(IndexPrivilege.All)
                )
            )
        )
    );

PHP Elasticsearch PHP Client

$resp = $client->security()->createApiKey([
    "body" => [
        "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.create_api_key(
  body: {
    "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

{
  "id": "VuaCfGcBCdbkQm-e5aOx",        
  "name": "my-api-key",
  "expiration": 1544068612110,         
  "api_key": "ui2lp2axTNmsyakw9tvNnw", 
  "encoded": "VnVhQ2ZHY0JDZGJrUW0tZTVhT3g6dWkybHAyYXhUTm1zeWFrdzl0dk5udw=="  
}

Required authorization

Query Parameters

Request { expiration , name , role_descriptors , metadata , }

Response

Request