CPS: Refactor auth-related stuff and small style edits

deploy-manage/_snippets/cps-definition.md

@@ -0,0 +1 @@
+With {{cps}} ({{cps-init}}), users in your organization can search across multiple {{serverless-full}} projects at once, instead of searching each project individually. When your data is split across projects to organize ownership, use cases, or environments, {{cps}} lets you query all the data from a single place. 

deploy-manage/cross-project-search-config.md

@@ -9,11 +9,12 @@ navigation_title: "Cross-project search"
 
 # Configure {{cps}} [configure-cross-project-search]
 
-With {{cps}} ({{cps-init}}), users in your organization can search across multiple {{serverless-full}} projects at once, instead of searching each project individually. When your data is split across projects to organize ownership, use cases, or environments, {{cps}} lets you query all the data from a single place. 
+::::{include} /deploy-manage/_snippets/cps-definition.md
+::::
 
 {{cps-cap}} is the {{serverless-short}} equivalent of [{{ccs}}](/explore-analyze/cross-cluster-search.md), with a few differences and enhancements:
 
-* Setting up cross-project search doesn't require an understanding of your deployment architecture or complex security configurations.
+* Setting up {{cps}} doesn't require an understanding of your deployment architecture or complex security configurations.
 * Permissions stay consistent across projects, and you can always adjust scope and access as needed. 
 * Searches are performed across projects by default, reducing the need to refactor your queries as you link additional projects.
 

deploy-manage/cross-project-search-config/cps-config-access-and-scope.md

@@ -13,30 +13,22 @@ This page explains how user permissions and scope affect {{cps}} ({{cps-init}})
 
 For more details about {{cps-init}} configuration, refer to [](/deploy-manage/cross-project-search-config.md). For information about _using_ {{cps-init}}, refer to [](/explore-analyze/cross-project-search.md).
 
-## Manage user access [manage-user-access]
+## Manage user and API key access
 
-Access to data in linked projects is determined by the [roles](/deploy-manage/users-roles/cluster-or-deployment-auth/user-roles.md) assigned to the user in each project. Whether a user queries a project directly or through {{cps}}, the same permissions apply.
-
-When a {{cps}} query reaches a linked project, the system verifies the user's identity and evaluates the roles assigned to that user in the linked project. Users can only access resources if their roles permit. This means {{cps}} results can vary by user, depending on each user's role assignments across projects.
-
-For example, if a user has read access to the `logs` index in Project B but not in Project C, a {{cps}} for `logs` returns documents from Project B and silently excludes Project C.
-
-For additional information, refer to [{{cps-init}} security](/explore-analyze/cross-project-search.md#security).
-
-% TODO ^^ snippetize from E&A
-
-## Manage programmatic access [cps-programmatic-access]
+:::{include} /explore-analyze/cross-project-search/_snippets/cps-security.md
+:::
 
-The same role-based access model applies to programmatic access through API keys. For {{cps}}, you must use [{{ecloud}} API keys](/deploy-manage/api-keys/elastic-cloud-api-keys.md), which can authenticate across project boundaries.
+### How access is evaluated
 
-Project-scoped API keys, such as [{{serverless-short}} project API keys](/deploy-manage/api-keys/serverless-project-api-keys.md), cannot search across project boundaries. If a project-scoped API key is used in a {{cps}} context, it silently returns results from the origin project only (no error is returned).
+:::{include} /explore-analyze/cross-project-search/_snippets/cps-access-evaluation.md
+:::
 
 ## Administrator tasks
 % TODO better heading
 
-- Make sure that users who need to search across linked projects have a [role assigned](/deploy-manage/users-roles.md) on each linked project they need to access. Authorization is evaluated on the linked project, without regard to the origin project.
+- Make sure that users who need to search across linked projects have a [role assigned](/deploy-manage/users-roles.md) on each linked project they need to access, and are granted **Cloud Console, {{es}}, and {{kib}}** access to those projects. Authorization is evaluated on the linked project, without regard to the origin project.
 - If a user reports missing data from a linked project, check their role assignment on that specific linked project first.
-- For programmatic access, make sure the {{ecloud}} API key has the appropriate [roles](/deploy-manage/api-keys/elastic-cloud-api-keys.md#roles) on each project the key needs to access.
+- For programmatic access, make sure the {{ecloud}} API key has the appropriate [roles](/deploy-manage/api-keys/elastic-cloud-api-keys.md#roles) on each project the key needs to access, and is granted **Cloud, {{es}}, and {{kib}} API access** to those projects.
 
 % TODO alerting impacts of user role changes 
 

explore-analyze/cross-project-search.md

@@ -9,19 +9,20 @@ description: Learn how cross-project search (CPS) enables you to search across m
 
 # {{cps-cap}} [cross-project-search]
 
-**{{cps-cap}}** ({{cps-init}}) enables you to run a single search request across multiple {{serverless-short}} projects.
-When your data is split across projects to organize ownership, use cases, or environments, {{cps}} lets you query all that data from a single place, without having to search each project individually.
+::::{include} /deploy-manage/_snippets/cps-definition.md
+::::
 
 {{cps-cap}} relies on linking projects within your {{ecloud}} organization. After you link projects together, searches from the origin project automatically run across all linked projects.
 
 This overview explains how {{cps}} works, including project linking and security.
-For prerequisites, compatibility requirements, architecture planning, and scope defaults, refer to [Configure {{cps}}](/deploy-manage/cross-project-search-config.md) in **Deploy and manage**.
+For prerequisites, compatibility requirements, architecture planning, and scope defaults, refer to [](/deploy-manage/cross-project-search-config.md).
+
 For details on how search, tags, and project routing work in {{cps-init}}, refer to the following pages:
 
 * [Search in {{cps-init}}](/explore-analyze/cross-project-search/cross-project-search-search.md): Learn how search expressions, search options, and index resolution work.
 * [Tags in {{cps-init}}](/explore-analyze/cross-project-search/cross-project-search-tags.md): Learn about predefined and custom project tags and how to use them in queries.
 * [Project routing in {{cps-init}}](/explore-analyze/cross-project-search/cross-project-search-project-routing.md): Learn how to route searches to specific projects based on tag values.
-* [Manage {{cps}} scope in your project apps](/explore-analyze/cross-project-search/cross-project-search-manage-scope.md): Control which projects are searched as you work in Discover, Dashboards, and other {{kib}} apps.
+* [Manage {{cps-init}} scope in your project apps](/explore-analyze/cross-project-search/cross-project-search-manage-scope.md): Control which projects are searched as you work in Discover, Dashboards, and other {{kib}} apps.
 
 ## {{cps-cap}} as the default behavior for linked projects
 
@@ -65,7 +66,7 @@ You can use `_origin` in search expressions to explicitly target the origin proj
 ## Excluding indices and projects
 
 You can exclude specific indices or projects from a {{cps}} by prefixing a pattern with a dash (`-`).
-This enables you start with a broad search scope and narrow it down by removing specific indices or projects from the results.
+This enables you to start with a broad search scope and narrow it down by removing specific indices or projects from the results.
 
 ### How exclusion works
 
@@ -105,22 +106,16 @@ The following examples assume an origin project with two linked projects: `linke
 
 This section gives you a high-level overview of how security works in {{cps}}.
 
-In {{cps-init}}, access to a project's data is determined by the [roles](/deploy-manage/users-roles/cluster-or-deployment-auth/user-roles.md) assigned to you in that project. Your access does not change based on how you perform a search: whether you query directly within a project or access it through {{cps}}, the same permissions apply.
-
-::::{note}
-{{cps-cap}} is not available when performing programmatic searches using {{es}} API keys, since they're project-scoped and they return results from the local project only.
-::::
-
-Access control operates in two stages:
-
-* Authentication verifies the identity associated with a request (for example, a Cloud user or API key) and retrieves that identity's role assignments in each project.
-* Authorization evaluates those roles to determine which actions and resources the request can access within each project.
+:::{include} /explore-analyze/cross-project-search/_snippets/cps-security.md
+:::
 
-For example, if you have a viewer role in project 1, an admin role in project 2, and a custom role in project 3, you can access all three projects through {{cps}}. Each project enforces the permissions associated with the role you have in that project.
+### How access is evaluated
 
-When a {{cps}} query targets a linked project that you have access to, authorization checks are performed locally in that project to determine whether you have the required privileges to access the requested resources.
+:::{include} /explore-analyze/cross-project-search/_snippets/cps-access-evaluation.md
+:::
 
 **Example**
+
 You have read access to the `logs` index in project 1, but no access to the `logs` index in project 2.
 If you run `GET logs/_search`:
 
@@ -178,7 +173,7 @@ For additional information, refer to the [{{product.painless}} execute API refer
 ::::{include} /deploy-manage/_snippets/cps-limitations-core.md
 ::::
 
-For administrator-focused details including compatibility, architecture patterns, and feature impacts, refer to [Configure {{cps}}](/deploy-manage/cross-project-search-config.md).
+For administrator-focused details including compatibility, architecture patterns, and feature impacts, refer to [](/deploy-manage/cross-project-search-config.md).
 
 ## {{cps-cap}} examples [cps-examples]
 

explore-analyze/cross-project-search/_snippets/cps-access-evaluation.md

@@ -0,0 +1,8 @@
+Access control operates in two stages:
+
+* Authentication verifies the identity associated with a request (for example, a Cloud user or API key) and retrieves that identity's role assignments in each project.
+* Authorization evaluates those roles to determine which actions and resources the request can access within each project.
+
+For example, if you have a viewer role in project 1, an admin role in project 2, and a custom role in project 3, you can access all three projects through {{cps}}. Each project enforces the permissions associated with the role you have in that project.
+
+When a {{cps}} query targets a linked project that you have access to, authorization checks are performed locally in that project to determine whether you have the required privileges to access the requested resources.

explore-analyze/cross-project-search/_snippets/cps-security.md

@@ -0,0 +1,13 @@
+* **From within {{kib}}:** Searches you run from the origin project use your [{{ecloud}} user role assignments](/deploy-manage/users-roles/cloud-organization/user-roles.md) on each project that participates in the search. Those assignments must include [Cloud Console, {{es}}, and {{kib}} access](/deploy-manage/users-roles/cloud-organization/user-roles.md#access) to those projects to return project data.
+
+* **Programmatically:** Requests authenticated with an [{{ecloud}} API key](/deploy-manage/api-keys/elastic-cloud-api-keys.md) use that key’s role assignments on each project. The key must have [Cloud, {{es}}, and {{kib}} API access](/deploy-manage/api-keys/elastic-cloud-api-keys.md#project-access) to those projects to return project data.
+
+Alternatively, a user or key can be granted organization-level roles that grant access to all projects in the organization.
+
+Permissions are always evaluated per project. It does not matter whether you query that project from its own endpoint or from an origin project linked through {{cps-init}}: the same role assignments apply.
+
+::::{admonition} Use {{ecloud}} API keys for {{cps-init}}
+For {{cps}}, you must use [{{ecloud}} API keys](/deploy-manage/api-keys/elastic-cloud-api-keys.md), which can authenticate across project boundaries. 
+
+{{cps-cap}} is not available when performing programmatic searches using [{{es}} API keys](/deploy-manage/api-keys/serverless-project-api-keys.md), because they're scoped to a single project. These keys return results from the origin project only.
+::::

explore-analyze/cross-project-search/cross-project-search-project-routing.md

@@ -8,12 +8,12 @@ description: Learn how to use project routing to limit cross-project search (CPS
 navigation_title: "Project routing"
 ---
 
-# Using project routing to limit search scope [cps-project-routing]
+# Using project routing to limit {{cps}} scope [cps-project-routing]
 
 Project routing enables you to limit a search to a subset of projects, including the origin project and linked projects, based on tag values.
 
 When you use project routing, the routing decision is made before the search request is performed.
-Based on the specified tags, {{cps-init}} determines which projects the query is sent to, and the search is performed only on those projects.
+Based on the specified tags, {{cps}} determines which projects the query is sent to, and the search is performed only on those projects.
 
 For an overview of {{cps}} concepts, refer to [{{cps-cap}}](/explore-analyze/cross-project-search.md). For details on available tags, refer to [Tags in {{cps-init}}](/explore-analyze/cross-project-search/cross-project-search-tags.md).
 

explore-analyze/cross-project-search/cross-project-search-tags.md

@@ -8,7 +8,7 @@ description: Learn about project tags in cross-project search (CPS), including p
 navigation_title: "Tags"
 ---
 
-# Using tags to control search [cps-tags]
+# Using tags to control {{cps}} [cps-tags]
 
 You can assign [tags](/deploy-manage/deploy/elastic-cloud/project-settings.md#project-tags) to projects and use them to control {{cps}} behavior.
 

explore-analyze/toc.yml

@@ -189,6 +189,8 @@ toc:
       - file: cross-project-search/cross-project-search-tags.md
       - file: cross-project-search/cross-project-search-project-routing.md
       - file: cross-project-search/cross-project-search-manage-scope.md
+      - title: "CPS in ES|QL"
+        crosslink: elasticsearch://reference/query-languages/esql/esql-cross-serverless-projects.md
   - file: ai-features.md
     children:
       - file: ai-features/elastic-agent-builder.md