[DOCS] Overview page for API keys

[n1v0lg]

Description

We currently only have documentation around concrete APIs for API keys, and no general overview page.

API keys are nuanced, both in terms when they should be used, as well as how their access scope is determined and configured.

We should introduce an overview page addressing (at a minimum):

• What are API keys and when should they be used?
• How is the access scope of an API key determined (i.e., role_descriptors vs. limited_by_role_descriptors)?

This would furthermore allow us to move conceptual (and currently duplicated) information from concrete API docs (e.g. the role_descriptors explanation in the create API key API docs) into the overview page and converge on a single source of truth for these concepts (within ES docs, at least).

Relates: #88499 (comment)

[elasticsearchmachine]

Pinging @elastic/es-docs (Team:Docs)

[elasticsearchmachine]

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

[n1v0lg]

I've labeled this team-discuss to validate that it doesn't clash with any broader efforts around security-related documentation.

@lockewritesdocs just wanted to confirm: putting together an ES-specific API keys overview page still makes sense, correct?

I'm raising this now, since I will soon work on documentation for the new bulk update route; putting together an overview page first potentially lets us avoid duplicating yet more concepts in the new API docs.

[lockewritesdocs]

putting together an ES-specific API keys overview page still makes sense, correct?

@n1v0lg, I absolutely think that an overview of API keys makes sense, and is necessary. I'm putting together an outline for an updated security guide, and authenticating with API keys is part of a section that I'm currently calling Machine authentication. The main content that's missing for a discussion of API keys is:

• What are the benefits of using them?
• When should you use them?

I think that the answer of when to use them is for when you're authenticating between machines, but we need to put more context around that usage.

[tvernum]

Related: #70702

[abdonpijpelink]

This has become more important with the release of API key based remote cluster security in 8.10. We now have three types of API key (ES, cross cluster, and ESS). This can be confusing, so some guidance on when to use which type of key, and how to create it, would be useful.

This doc would also be a good place to discuss how privileges work for the different keys.