Serverless admin user and API-only key workflow improvements (#7277)

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

---------

Co-authored-by: wajihaparvez <wajiha.parvez@elastic.co>

Author: eedugon

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

@@ -8,12 +8,11 @@ navigation_title: Manage projects with API
 
 # Manage serverless projects using the API [serverless-api]
 
-On this page, you can find examples of how to create and manage serverless projects using the [Elastic Cloud Serverless API]({{cloud-serverless-apis}}), covering common operations such as:
+On this page, you can find examples of how to create and manage serverless projects using the [{{serverless-full}} API]({{cloud-serverless-apis}}), covering common operations such as:
 
 - [Creating a project](#general-manage-project-with-api-create-a-serverless-elasticsearch-project)
 - [Retrieving project details](#general-manage-project-with-api-get-project)
 - [Retrieving the project's status](#general-manage-project-with-api-get-project-status)
-- [Resetting credentials](#general-manage-project-with-api-reset-credentials)
 - [Deleting a project](#general-manage-project-with-api-delete-project)
 - [Updating a project](#general-manage-project-with-api-update-project)
 - [Listing regions where projects can be created](#general-manage-project-with-api-list-available-regions)
@@ -26,7 +25,7 @@ To try the examples in this section, start by [setting up an API key](#general-m
 
 ## API resources
 
-To learn about API principles, authentication, and how to use the OpenAPI specification, refer to the [Elastic Cloud Serverless API]({{cloud-serverless-apis}}) documentation.
+To learn about API principles, authentication, and how to use the OpenAPI specification, refer to the [{{serverless-full}} API]({{cloud-serverless-apis}}) documentation.
 
 The available APIs are grouped by project type:
 
@@ -36,12 +35,20 @@ The available APIs are grouped by project type:
 
 ## Set up an API key [general-manage-project-with-api-set-up-api-key]
 
-1. [Create an API key](https://www.elastic.co/docs/deploy-manage/api-keys/elastic-cloud-api-keys).
+To create and manage projects with the {{serverless-full}} API, you must authenticate your requests with an {{ecloud}} API key.
+
+1. As an **Organization owner**, [create an {{ecloud}} API key](/deploy-manage/api-keys/elastic-cloud-api-keys.md) with one of the following roles:
+
+   - **Organization owner**
+   - **Cloud resource access** with the **Admin** role assigned to **all projects** of the relevant type ({{es}}, {{observability}}, or Security)
+
+   Select the key's **API access** level based on what you need it to do: **Cloud API** access is enough to manage projects, while **Cloud, {{es}}, and {{kib}} API** access also grants access to the project's {{es}} and {{kib}} endpoints. For more details, refer to [User roles and privileges](/deploy-manage/users-roles/cloud-organization/user-roles.md).
+
 2. Store the generated API key as an environment variable so that you don’t need to specify it again for each request:
 
-```console
-export API_KEY="YOUR_GENERATED_API_KEY"
-```
+   ```console
+   export API_KEY="YOUR_GENERATED_API_KEY"
+   ```
 
 ## Create an {{serverless-full}} project [general-manage-project-with-api-create-a-serverless-elasticsearch-project]
 
@@ -61,7 +68,7 @@ curl -H "Authorization: ApiKey $API_KEY" \
 1. Replace `My project` with a more descriptive name in this call.
 2. You can obtain a [list of available regions](#general-manage-project-with-api-list-available-regions). 
 
-The response from the create project request will include the created project details, such as the project ID, the credentials to access the project, and the endpoints to access different apps such as {{es}} and {{kib}}.
+The response from the create project request will include the created project details, including the project ID, the endpoints to access different apps such as {{es}} and {{kib}}, and a set of default credentials.
 
 Example of `Create project` response:
 
@@ -80,6 +87,12 @@ Example of `Create project` response:
 }
 ```
 
+:::{note}
+For programmatic access to the project's {{es}} and {{kib}} APIs, we recommend creating an [{{ecloud}} API key with access to the {{es}} and {{kib}} APIs](/deploy-manage/api-keys/elastic-cloud-api-keys.md#project-access) rather than using the default credentials.
+
+The default credentials returned in the `credentials` field serve as a fallback mechanism to access the project when no API key is available. Store them in a secure location, and use the [reset credentials API]({{cloud-serverless-apis}}operation/operation-resetelasticsearchprojectcredentials) if you need to recover or rotate them.
+:::
+
 You can store the project ID as an environment variable for the next requests:
 
 ```console
@@ -112,16 +125,6 @@ Example response:
 }
 ```
 
-## Reset credentials [general-manage-project-with-api-reset-credentials]
-
-If you lose the credentials provided at the time of the project creation, you can reset the credentials by using the following endpoint:
-
-```bash
-curl -H "Authorization: ApiKey $API_KEY" \
-    -XPOST \
-    "https://api.elastic-cloud.com/api/v1/serverless/projects/elasticsearch/${PROJECT_ID}/_reset-credentials"
-```
-
 ## Delete a project [general-manage-project-with-api-delete-project]
 
 You can delete your project via the API: