Create an API key Added in 6.7.0

PUT /_security/api_key

Create an API key for access without requiring basic authentication. 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.

Query parameters

  • refresh string

    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 are true, false, or wait_for.

application/json

Body Required

  • expiration string

    A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.

  • name string
  • role_descriptors object

    An array of role descriptors for this API key. This parameter is optional. When it is not specified or is an empty array, then the API key will have a point in time snapshot of permissions of the authenticated user. If you supply role descriptors then the resultant permissions would be an intersection of API keys permissions and authenticated user’s permissions thereby limiting the access scope for API keys. The structure of role descriptor is the same as the request for create role API. For more details, see create or update roles API.

    Hide role_descriptors attribute Show role_descriptors attribute object
    • * object Additional properties

      Additional properties are allowed.

      Hide * attributes Show * attributes object
      • cluster array[string]

        A list of cluster privileges. These privileges define the cluster level actions that API keys are able to execute.

      • indices array[object]

        A list of indices permissions entries.

        Hide indices attributes Show indices attributes object
      • applications array[object]

        A list of application privilege entries

        Hide applications attributes Show applications attributes object
        • application string Required

          The name of the application to which this entry applies.

        • privileges array[string] Required

          A list of strings, where each element is the name of an application privilege or action.

        • resources array[string] Required

          A list resources to which the privileges are applied.

      • metadata object
        Hide metadata attribute Show metadata attribute object
        • * object Additional properties

          Additional properties are allowed.

      • run_as array[string]

        A list of users that the API keys can impersonate. Note: in Serverless, the run-as feature is disabled. For API compatibility, you can still specify an empty run_as field, but a non-empty list will be rejected.

      • description string

        Optional description of the role descriptor

      • restriction object

        Additional properties are allowed.

        Hide restriction attribute Show restriction attribute object
      • transient_metadata object
        Hide transient_metadata attribute Show transient_metadata attribute object
        • * object Additional properties

          Additional properties are allowed.

  • metadata object
    Hide metadata attribute Show metadata attribute object
    • * object Additional properties

      Additional properties are allowed.

Responses

  • 200 application/json
    Hide response attributes Show response attributes object
    • api_key string Required

      Generated API key.

    • expiration number

      Expiration in milliseconds for the API key.

    • id string Required
    • name string Required
    • encoded string Required

      API key credentials which is the base64-encoding of the UTF-8 representation of id and api_key joined by a colon (:).
PUT /_security/api_key 
curl \
 -X PUT http://api.example.com/_security/api_key \
 -H "Content-Type: application/json" \
 -d '{"expiration":"string","name":"string","role_descriptors":{"additionalProperty1":{"cluster":["string"],"indices":[{"field_security":{"except":"string","grant":"string"},"names":"string","privileges":["string"],"":"string"}],"applications":[{"application":"string","privileges":["string"],"resources":["string"]}],"metadata":{"additionalProperty1":{},"additionalProperty2":{}},"run_as":["string"],"description":"string","restriction":{"workflows":["string"]},"transient_metadata":{"additionalProperty1":{},"additionalProperty2":{}}},"additionalProperty2":{"cluster":["string"],"indices":[{"field_security":{"except":"string","grant":"string"},"names":"string","privileges":["string"],"":"string"}],"applications":[{"application":"string","privileges":["string"],"resources":["string"]}],"metadata":{"additionalProperty1":{},"additionalProperty2":{}},"run_as":["string"],"description":"string","restriction":{"workflows":["string"]},"transient_metadata":{"additionalProperty1":{},"additionalProperty2":{}}}},"metadata":{"additionalProperty1":{},"additionalProperty2":{}}}'