Grant an API key Added in 7.9.0

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 (either an access token, or a username and password) 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 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.

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.

application/json

Body Required

  • api_key object Required

    Additional properties are allowed.

    Hide api_key attributes Show api_key attributes object
    • name string Required
    • expiration string

      A date histogram interval. Similar to Duration with additional units: w (week), M (month), q (quarter) and y (year)

    • role_descriptors object | array[object]

      The role descriptors for this API key. This parameter is optional. When it is not specified or is an empty array, the API key has a point in time snapshot of permissions of the specified user or access token. If you supply role descriptors, the resultant permissions are an intersection of API keys permissions and the permissions of the user or access token.

      One of:
      object-1 object array-2 array[object]
      Hide attribute Show 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.

          Additional properties are allowed.

        • global array[object] | object

          An object defining global privileges. A global privilege is a form of cluster privilege that is request-aware. Support for global privileges is currently limited to the management of application privileges.

          One of:
          array-1 array[object] _types:GlobalPrivilege object

          Additional properties are allowed.

        • applications array[object]

          A list of application privilege entries

          Additional properties are allowed.

        • 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

        • 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.

  • grant_type string Required

    Values are access_token or password.

  • access_token string

    The user’s access token. If you specify the access_token grant type, this parameter is required. It is not valid with other grant types.

  • username string
  • password string
  • run_as string

Responses

POST /_security/api_key/grant 
curl \
 -X POST http://api.example.com/_security/api_key/grant \
 -H "Content-Type: application/json" \
 -d '{"api_key":{"name":"string","expiration":"string","role_descriptors":{"additionalProperty1":{"cluster":["string"],"indices":[{"field_security":{},"names":["string"],"privileges":["string"],"allow_restricted_indices":true}],"global":[{}],"applications":[{"application":"string","privileges":["string"],"resources":["string"]}],"metadata":{"additionalProperty1":{},"additionalProperty2":{}},"run_as":["string"],"description":"string","transient_metadata":{"additionalProperty1":{},"additionalProperty2":{}}},"additionalProperty2":{"cluster":["string"],"indices":[{"field_security":{},"names":["string"],"privileges":["string"],"allow_restricted_indices":true}],"global":[{}],"applications":[{"application":"string","privileges":["string"],"resources":["string"]}],"metadata":{"additionalProperty1":{},"additionalProperty2":{}},"run_as":["string"],"description":"string","transient_metadata":{"additionalProperty1":{},"additionalProperty2":{}}}},"metadata":{"additionalProperty1":{},"additionalProperty2":{}}},"grant_type":"access_token","access_token":"string","username":"string","password":"string","run_as":"string"}'
Request examples 
{
  "api_key": {
    "name": "string",
    "expiration": "string",
    "role_descriptors": {
      "additionalProperty1": {
        "cluster": [
          "string"
        ],
        "indices": [
          {
            "field_security": {},
            "names": [
              "string"
            ],
            "privileges": [
              "string"
            ],
            "allow_restricted_indices": true
          }
        ],
        "global": [
          {}
        ],
        "applications": [
          {
            "application": "string",
            "privileges": [
              "string"
            ],
            "resources": [
              "string"
            ]
          }
        ],
        "metadata": {
          "additionalProperty1": {},
          "additionalProperty2": {}
        },
        "run_as": [
          "string"
        ],
        "description": "string",
        "transient_metadata": {
          "additionalProperty1": {},
          "additionalProperty2": {}
        }
      },
      "additionalProperty2": {
        "cluster": [
          "string"
        ],
        "indices": [
          {
            "field_security": {},
            "names": [
              "string"
            ],
            "privileges": [
              "string"
            ],
            "allow_restricted_indices": true
          }
        ],
        "global": [
          {}
        ],
        "applications": [
          {
            "application": "string",
            "privileges": [
              "string"
            ],
            "resources": [
              "string"
            ]
          }
        ],
        "metadata": {
          "additionalProperty1": {},
          "additionalProperty2": {}
        },
        "run_as": [
          "string"
        ],
        "description": "string",
        "transient_metadata": {
          "additionalProperty1": {},
          "additionalProperty2": {}
        }
      }
    },
    "metadata": {
      "additionalProperty1": {},
      "additionalProperty2": {}
    }
  },
  "grant_type": "access_token",
  "access_token": "string",
  "username": "string",
  "password": "string",
  "run_as": "string"
}
Response examples (200) 
{
  "api_key": "string",
  "id": "string",
  "name": "string",
  "": 42.0,
  "encoded": "string"
}