elasticsearch/x-pack/docs/en/rest-api/security/create-api-keys.asciidoc

[role="xpack"]
[[security-api-create-api-key]]
=== Create API Key API

Creates an API key for access without requiring basic authentication.

==== Request

`POST /_security/api_key`
`PUT /_security/api_key`

==== Description

The API keys are created by the {es} API key service, which is automatically enabled
when you configure TLS on the HTTP interface. See <<tls-http>>. Alternatively,
you can explicitly enable the `xpack.security.authc.api_key.enabled` setting. When 
you are running in production mode, a bootstrap check prevents you from enabling 
the API key service unless you also enable TLS on the HTTP interface. 

A successful create API key API call returns a JSON structure that contains 
the unique id, the name to identify API key, the API key and the expiration if 
applicable for the API key in milliseconds. 

NOTE: By default API keys never expire. You can specify expiration at the time of 
creation for the API keys. 

See <<api-key-service-settings>> for configuration settings related to API key service.

==== Request Body

The following parameters can be specified in the body of a POST or PUT request:

`name`::
(string) Specifies the name for this API key.

`role_descriptors`::
(array-of-role-descriptor) Optional array of role descriptor for this API key. The role descriptor 
must be a subset of permissions of the authenticated user. The structure of role 
descriptor is same as the request for create role API. For more details on role 
see <<security-api-roles, Role Management APIs>>.
If the role descriptors are not provided then permissions of the authenticated user are applied.

`expiration`::
(string) Optional expiration time for the API key. By default API keys never expire.

==== Examples

The following example creates an API key:

[source, js]
------------------------------------------------------------
POST /_security/api_key
{
  "name": "my-api-key",
  "expiration": "1d", <1>
  "role_descriptors": { <2>
    "role-a": {
      "cluster": ["all"],
      "index": [
        {
          "names": ["index-a*"],
          "privileges": ["read"]
        }
      ]
    },
    "role-b": {
      "cluster": ["all"],
      "index": [
        {
          "names": ["index-b*"],
          "privileges": ["all"]
        }
      ]
    }
  }
}
------------------------------------------------------------
// CONSOLE
<1> optional expiration for the API key being generated. If expiration is not
 provided then the API keys do not expire.
<2> optional role descriptors for this API key, if not provided then permissions
 of authenticated user are applied.

A successful call returns a JSON structure that provides
API key information.

[source,js]
--------------------------------------------------
{
  "id":"VuaCfGcBCdbkQm-e5aOx", <1>
  "name":"my-api-key",
  "expiration":1544068612110, <2>
  "api_key":"ui2lp2axTNmsyakw9tvNnw" <3>
}
--------------------------------------------------
// TESTRESPONSE[s/VuaCfGcBCdbkQm-e5aOx/$body.id/]
// TESTRESPONSE[s/1544068612110/$body.expiration/]
// TESTRESPONSE[s/ui2lp2axTNmsyakw9tvNnw/$body.api_key/]
<1> unique id for this API key
<2> optional expiration in milliseconds for this API key
<3> generated API key

The API key returned by this API can then be used by sending a request with a
`Authorization` header with a value having the prefix `ApiKey ` followed
by the _credentials_, where _credentials_ is the base64 encoding of `id` and `api_key` joined by a colon.

[source,shell]
--------------------------------------------------
curl -H "Authorization: ApiKey VnVhQ2ZHY0JDZGJrUW0tZTVhT3g6dWkybHAyYXhUTm1zeWFrdzl0dk5udw==" http://localhost:9200/_cluster/health
--------------------------------------------------
// NOTCONSOLE