Today, API key attributes, including metadata and roles, are immutable, i.e., cannot be changed after an API key has been created.

There are use cases for API keys in which both the metadata and, importantly, the roles associated with an API key change. The current approach to solve this is rotation: invalidating the old key, creating a new one with the desired attributes, and replacing the use of the old key. This can be both cumbersome and performance intensive.

This issue proposes to implement a new route PUT /_security/api_key/{id} through which the following attributes of an API key can be updated:

• role_descriptors - The list of role descriptors specified for the key. This is one of the two parts that determines an API key’s privileges.
• metadata_flattened - The searchable metadata associated to an API key

Several other attributes will be automatically updated for each call, including:

• limited_by_role_descriptors - The snapshot of owner user’s privilege. This is the other part that determines an API key’s privileges.
• creator - The snapshot of owner user’s information, including principal, full_name, email, metadata, realm and domain.
• version - This field represents the minimal node version when the API key is first created. It is not currently used. Updating an API key should also bring its format to the latest version, e.g. adding metadata which is not available before v7.13. Therefore we should also update this field to the current minimum node version.

Only the creator of an API key is authorized to update it, provided the manage_own_api_key privilege.

This breaks down into the following tasks:

• Service level implementation (ApiKeyService), including caching and automatic format updates for version changes
• REST and transport layer, including permissions