Hi @tvernum, I've created a changelog YAML for you.

🔍 Preview links for changed docs

• docs/reference/elasticsearch/security-privileges.md

ℹ️ Important: Docs version tagging

👋 Thanks for updating the docs! Just a friendly reminder that our docs are now cumulative. This means all 9.x versions are documented on the same page and published off of the main branch, instead of creating separate pages for each minor version.

We use applies_to tags to mark version-specific features and changes.

🤔 Need help?

• Check out the cumulative docs guidelines
• Reach out in the #docs Slack channel

Purpose

This PR adds a Clone API Key REST API so that a user with the right privileges can create a new API key that has the same role descriptors and owner as an existing API Key. The source API Key is identified by supplying its encoded credential in the request.

Use case: When the caller would normally use Grant API Key (creating an API key on behalf of a user), but the authenticating credential is itself an API key.
Elasticsearch does not support “derived” API keys (an API key creating another API key). This endpoint lets a client (e.g. Kibana) clone the user’s API key for its own internal use instead of using Grant API Key with that key (which doesn't work)

REST API

• Path: /_security/api_key/clone
• Methods: POST, PUT (same as Grant API Key)
• Body : Required, see below
• Query Parameters: Optional refresh (true | false | wait_for).
• Headers: Standard authentication headers for the orchestrating user (e.g. Kibana service account)

Request body

Examples:

Minimal required fields

{
  "api_key": "VnVhQ2ZHY0RvZGZWekVXTmJPRVp3YUdwe...",
  "name": "my-cloned-key"
}

All supported fields

{
  "api_key": "VnVhQ2ZHY0RvZGZWekVXTmJPRVp3YUdwe...",
  "name": "my-cloned-key",
  "expiration": "30d",
  "metadata": {
    "environment": "staging",
    "purpose": "CI pipeline"
  }
}

Response

Same as Create API Key / Grant API Key: CreateApiKeyResponse with id, name, api_key, expiration, encoded.

Example:

{
  "id": "A1b2C3d4E5f6G7h8I9j0K",
  "name": "my-cloned-key",
  "api_key": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
  "expiration": 1740268800000,
  "encoded": "QTFiOEMzZDRFNWY2RzdoOEo5ajBLOmExYjJjM2Q0ZTVmNmc3aDhpOWowazFsMm0zbjRvNXA2"
}

3. Behaviour

• Source key: Must be a valid, non-expired, non-invalidated REST API key. Only REST API keys can be cloned; cross-cluster or other types are rejected. The credential (including the secret) is required (proof of possession), you cannot clone an API Key purely by id
• New key: Has a new id and secret (that is, is a new credential); has the same privileges (role_descriptors) as the source (this includes both the original owner's limited roles, and any role descriptors that were assigned at creation). The creator is the source key’s creator (not the user calling the clone endpoint).
• Expiration: By default the new API Key expires at the same time (that is, the same point in time, not the same duration) as the source API Key, but this can be overridden by the caller.
  It is valid for an expiring API Key to be cloned into a non-expiring API Key (or an API key with a long expiry).
  This behaviour allows for rotating API Keys where an API Key can be created with an explicit expiry (e.g. 90 days) and then, if it is still in use and needed an appropriately privileged user can create a clone with a new expiry (another 90 days).
• Metadata: By default copied from source, but may be fully replaced by request body.
  In all cases the server adds _cloned_from = source key id.
  Request metadata must not use keys under the reserved _ prefix (including _cloned_from).
• Errors:
  • Invalid/missing credential or bad format → 400
  • Invalid/expired source key or unauthorized caller → 401/403 (REST layer maps UNAUTHORIZED to FORBIDDEN for consistency with Grant).
• Serverless: This API is INTERNAL in Serverless (as per Grant API Key) and the new privilege is not available for use in roles.

4. Security model

• Privilege: New cluster privilege clone_api_key, action cluster:admin/xpack/security/api_key/clone. Same pattern as grant_api_key. manage_security also allows the action.
• Kibana: The Kibana system reserved role gets clone_api_key so Kibana can call the endpoint when the user authenticates with an API key.
• manage_own_api_key: Explicitly does not allow clone (same as Grant): ManageOwnApiKeyClusterPrivilege returns false for CloneApiKeyRequest, so a dedicated clone_api_key (or manage_security) is required.
• Authorization: Caller must have clone_api_key (or broader). The source key is not authorised by a separate index/key privilege; possession of the API key credential is the proof that the caller is allowed to clone that key.
• Sensitive data: The api_key body field is filtered from logs and audit via RestRequestFilter (getFilteredFields() returns "api_key"), same as password/access_token for Grant API Key.
• Operator Privileges: The new action is not operator-only in stateful, but is INTERNAL in Serverless.

5. Implementation details (for reviewers)

• Request id: CloneApiKeyRequest generates the new key’s id in the no-arg constructor (UUIDs.base64UUID()) so that id is fixed for the request and can be audited; the actual document is written with this id in ApiKeyService.createApiKeyFromClone.
• Validation reuse: API key name and metadata validation are centralised in Validation.ApiKey (validateName, validateMetadata). AbstractCreateApiKeyRequest now uses these helpers instead of inlining checks; CloneApiKeyRequest uses the same validation.
• ApiKeyService refactor for clone:
  • loadApiKeyDoc: New helper that only loads the API key document (with cache).
  • loadApiKeyAndValidateCredentials now returns AuthenticationResult<Tuple2<User, ApiKeyDoc>> and uses loadApiKeyDoc plus credential validation, so both auth and clone can reuse it (clone needs the doc for role descriptors and creator).
  • AuthenticationResult.map(Function): New method to transform the success value; used so tryAuthenticate can keep returning AuthenticationResult<User> while internally using the tuple (e.g. response.map(Tuple::v1)).
  • validateCloneableApiKeyAndGetDoc: Ensures the key is REST type, then runs load + credential validation and returns the ApiKeyDoc for the clone path.
  • newDocument / creator: A new overload of newDocument takes a Map<String, Object> creator instead of Authentication. creatorMapFromAuthentication builds that map; the existing addCreator(builder, authentication) now delegates to it. Clone passes the source key’s creator map so the cloned key has the same creator.
  • Role descriptors: The internal helper that writes role descriptors is renamed to addAssignedRoleDescriptors for clarity (and now takes Collection).
• REST: RestCloneApiKeyAction implements RestRequestFilter and filters api_key. UNAUTHORIZED from the transport layer is converted to FORBIDDEN in the REST response (same pattern as RestGrantApiKeyAction). Scope is @ServerlessScope(Scope.INTERNAL).
• Docs: clone_api_key is documented in security-privileges.md with {applies_to}serverless: unavailable.

Pinging @elastic/es-security (Team:Security)

Vale Linting Results

Summary: 1 suggestion found

The Vale linter checks documentation changes against the Elastic Docs style guide.

To use Vale locally or report issues, refer to Elastic style guide for Vale.