Serverless admin user and API-only key workflow improvements

[eedugon]

Summary

Clarifies the confusion around the built-in admin user returned when creating
Serverless projects via the API (see elastic/docs-content-internal#546).

• manage-serverless-projects-using-api:
  • Reworked "Set up an API key" to specify the minimum roles (Organization owner, or
    Cloud resource Admin scoped to all projects) and the difference between Cloud API
    and Cloud + Elasticsearch/Kibana API access.
  • Added a note explaining what the built-in admin user is, why it exists, and
    recommending Elastic Cloud API keys with project access instead.
  • Reframed "Reset credentials" to clarify it resets the admin user, with use cases.
• differences-from-other-elasticsearch-offerings: added a footnote to the
  Native realm authentication row noting the single built-in admin user, so the
  comparison table no longer contradicts the API docs.

Closes https://github.com/elastic/docs-content-internal/issues/546

Generative AI disclosure

1. Did you use a generative AI (GenAI) tool to assist in creating this contribution?

• Yes - Cursor in auto mode
• No

[github-actions]

Elastic Docs AI PR menu

Check the box to run an AI review for this pull request.

• Review docs changes (docs-review). Status: not started.

Powered by GitHub Agentic Workflows and docs-actions. For more information, reach out to the docs team.

[github-actions]

🔍 Preview links for changed docs

• deploy-manage/deploy/elastic-cloud/manage-serverless-projects-using-api.md

[github-actions]

✅ Elastic Docs Style Checker (Vale)

No issues found on modified lines!

---

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.

[ppf2]

I think this is a good direction if we have decided to advertise the built-in admin user/password.

That said, I would like to defer to @bytebilly on how we are communicating this, given that it is going into public documentation. Given that, the admin user is:

1. Considered a secret that is exposed in plaintext in our API response. We may want to warn customers to not log the response from the API call.
2. A built-in user that represents an over privileged default identity. We may want to advise customers to store this user/password in a secret manager.
3. There is no default rotation of password for the admin user. We may want to advise customers to perform rotation themselves (I'm assuming there's a way for them to do this).

Now that I am writing this ... I wonder if we should also seek guidance from our Infosec team on any risks they see in documenting the details publicly 😅

[wajihaparvez]

LGTM! Can have another look if the content needs to be changed

[bytebilly]

I'd like to consider framing the admin credentials as not being a user, since they're not from a high-level perspective. They're more similar to an API key, and they should be used for programmatic access only.

[bytebilly]

LGTM 👍

[eedugon]

@ppf2 , if possible we'd like to get your final review here after the latest updates.
Thanks!

[ppf2]

@kunisen Would you mind lending a second pair of eyes on this? I know this is a topic that's close to your heart 🙂

[kunisen]

Thanks @ppf2 for your comment 🙏

Overall

@bytebilly has already given LGTM, so I am also good with the statement :)
Based on that, thinking in customer situation, I may have below two thoughts:

---

[1]

@eedugon I have one question:

• Does admin have programmatic access to the project's Elasticsearch and Kibana APIs?

I guess no? (Because API key with ES/Kibana API access is fairly recent feature IIRC).

Then WDYT we add:

• This username/password credential also does not have the access to the project's Elasticsearch and Kibana APIs
• (or statements logically similar)

So that we can make it more clear that this credential actually is not at the same level of API keys, to make it more explanatory of why we recommend API keys.

(I can see it's also in line with what Seb said in this comment - there won't be a need for the 'admin' basic auth user anymore. So IMHO, good to emphasize it more explicitly.)

---

[2]

when no API key is available

@eedugon per the comment from Seb, I take the reason of keeping admin user is "for backward compatibility reasons only (don't break the automation of existing customers)".

Do you think it's good to add this into the doc? Something like,

• For historical reasons, there were situations of no API key scenarios.
• But from now on, we recommend every use case to use API key.
• This credential should only be used for for backward compatibility reasons, etc.

---

It doesn't mean I am against with the statement.
The goal is to make things more clear based on Seb's comment, as well as the customer perspective. (given them more technical and logical evidence of why we recommend API key).

Hope it makes logical sense and thank you!

[eedugon]

@kunisen , I'll allow @bytebilly to add more context if he considers necessary.

Does admin have programmatic access to the project's Elasticsearch and Kibana APIs? I guess no?

Yes it does, not as an API key, but with user / password authentication. And precisely because of that we don't want to highlight the user and password or examples too much. We just say that they are default credentials to access the projects (which is true and valid), that they should be kept safe, and that they can be reset.

per the comment from Seb, I take the reason of keeping admin user is "for backward compatibility reasons only (don't break the automation of existing customers)"

I don't see the reason to add such a context, but if @bytebilly wants we can somehow tweak this sentence and make it a bit longer:

The default credentials returned in the credentials field serve as a fallback mechanism to access the project when no API key is available.

Update: I forgot about this:

The goal is to make things more clear based on Seb's comment

That was the goal I had in mind initially, but it's not the real goal here, sorry for the confusion.

The goal is to make user our users use Elastic Cloud API keys to access Elasticsearch and Kibana programmatically, and don't use these credentials. The secondary goal is to reduce the visibility of these credentials as an option. But we have decided to not remove them entirely because they are still returned by the create project API.

[bytebilly]

I'm not sure we want to mention backward compatibility, since in Serverless it's always been the case.

[kunisen]

Thanks both! Now I got the full picture and everything is clear on my side! 🙇 It looks great!

[eedugon]

Perfect, merging then! Thanks all!