---
title: Manage access and scope for cross-project search
description: This page explains how user permissions and scope affect cross-project search (CPS) behavior, and how to set a default scope at the space level. For details...
url: https://docs-v3-preview.elastic.dev/elastic/docs-content/tree/main/deploy-manage/cross-project-search-config/cps-config-access-and-scope
products:
  - Elastic Cloud Serverless
applies_to:
  - Elastic Cloud Serverless: Preview
  - Elastic Stack: Unavailable
---

# Manage access and scope for cross-project search
This page explains how user permissions and scope affect [cross-project search](https://docs-v3-preview.elastic.dev/elastic/docs-content/tree/main/deploy-manage/cross-project-search-config) (CPS) behavior, and how to set a default scope at the space level.
For details about how CPS scope works in Kibana, refer to [Managing cross-project search scope in your project apps](https://docs-v3-preview.elastic.dev/elastic/docs-content/tree/main/explore-analyze/cross-project-search/cross-project-search-manage-scope).

## Manage user and API key access

- **From within Kibana:** Searches you run from the origin project use your [Elastic Cloud user role assignments](https://docs-v3-preview.elastic.dev/elastic/docs-content/tree/main/deploy-manage/users-roles/cloud-organization/user-roles) on each project that participates in the search. Each role assignment must include [Cloud Console, Elasticsearch, and Kibana access](/elastic/docs-content/tree/main/deploy-manage/users-roles/cloud-organization/user-roles#access) to those projects to return project data.
- **Programmatically:** Requests authenticated with an [Elastic Cloud API key](https://docs-v3-preview.elastic.dev/elastic/docs-content/tree/main/deploy-manage/api-keys/elastic-cloud-api-keys) use that key’s role assignments on each project. Each role assignment must include [Cloud, Elasticsearch, and Kibana API access](/elastic/docs-content/tree/main/deploy-manage/api-keys/elastic-cloud-api-keys#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: the same role assignments apply.
<admonition title="Use Elastic Cloud API keys for CPS">
  For cross-project search, you must use [Elastic Cloud API keys](https://docs-v3-preview.elastic.dev/elastic/docs-content/tree/main/deploy-manage/api-keys/elastic-cloud-api-keys), which can authenticate across project boundaries.Cross-project search is not available when performing programmatic searches using [Elasticsearch API keys](https://docs-v3-preview.elastic.dev/elastic/docs-content/tree/main/deploy-manage/api-keys/serverless-project-api-keys), because they're scoped to a single project. These keys return results from the origin project only.
</admonition>


### How access is evaluated

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 cross-project search. Each project enforces the permissions associated with the role you have in that project.
When a cross-project search 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.

## Administrator tasks

- Make sure that users who need to search across linked projects have a [role assigned](https://docs-v3-preview.elastic.dev/elastic/docs-content/tree/main/deploy-manage/users-roles) on each linked project they need to access, and are granted **Cloud Console, Elasticsearch, and Kibana** 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 Elastic Cloud API key has the appropriate [roles](/elastic/docs-content/tree/main/deploy-manage/api-keys/elastic-cloud-api-keys#roles) on each project the key needs to access, and is granted **Cloud, Elasticsearch, and Kibana API access** to those projects.


## Manage cross-project search scope


### About CPS scope

The CPS _scope_ is the set of searchable resources included in a cross-project search. The scope can be:
- Origin project + all linked projects (default)
- Origin project + a set of linked projects, as defined by project routing
- Origin project only

The scope is further restricted by the user's or key's permissions.
Users can also set the scope at the query level, using [qualified search expressions](/elastic/docs-content/tree/main/explore-analyze/cross-project-search/cross-project-search-search#search-expressions) or [project routing](https://docs-v3-preview.elastic.dev/elastic/docs-content/tree/main/explore-analyze/cross-project-search/cross-project-search-project-routing).
By default, an unqualified search from an origin project targets the searchable resources in **all** linked projects, plus the searchable resources in the origin project. This default scope is intentionally broad, to provide the best user experience for searching across linked projects.
<important>
  The system-level default CPS scope can cause unexpected behavior, especially for alerts and dashboards that operate on the new combined dataset of the origin and all linked projects. To limit this behavior, set the [default CPS scope for each space](#cps-default-search-scope), _before_ you link projects.
</important>

The following actions change the scope of cross-project searches:
- **Administrator actions:**
  - Setting the [default cross-project search scope for a space](#cps-default-search-scope)
- Adjusting [user permissions](#manage-user-and-api-key-access) using roles or API keys (for example, creating Elastic Cloud API keys that span multiple projects)
- **User actions:**
  - Using the [CPS scope selector](/elastic/docs-content/tree/main/explore-analyze/cross-project-search/cross-project-search-manage-scope#cps-in-kibana) in the project header
- Using [qualified search expressions](/elastic/docs-content/tree/main/explore-analyze/cross-project-search/cross-project-search-search#search-expressions)
- Using [project routing](https://docs-v3-preview.elastic.dev/elastic/docs-content/tree/main/explore-analyze/cross-project-search/cross-project-search-project-routing)

The scope controls which projects receive the search request, while [querying and filtering](https://docs-v3-preview.elastic.dev/elastic/docs-content/tree/main/explore-analyze/query-filter) determine which results are returned by the search.

### Set the default CPS scope for a space

You can adjust the CPS system-level default scope by setting a narrower cross-project search scope for each space. This setting determines the default search scope for the space. Users can override both the system-level default and the space-level default by setting their preferred scope when searching, filtering, or running queries.
<tip>
  For best results, set the default CPS scope for each space **before** you link projects.
</tip>

Space settings are managed in Kibana.
1. To open space settings, click **Manage spaces** at the top of the **Cross-project search** page. Select the space you want to configure.

1. In the general space settings, find the **Cross-project search** panel and set the default scope for the space:
   - **All projects:** (default) Searches run across the origin project and all linked projects.
- **This project:**  Searches run only against the origin project's data.
2. Click **Apply changes** to save the scope setting.

<note>
  The default cross-project search scope is a space setting, not an access control. Users can still set the scope at the query level. You can also [manage user access](#manage-user-and-api-key-access).
</note>


## Next steps

- Review [Managing cross-project search scope in your project apps](https://docs-v3-preview.elastic.dev/elastic/docs-content/tree/main/explore-analyze/cross-project-search/cross-project-search-manage-scope) for more information about how CPS works with compatible Kibana apps, including how users can adjust search scope.
- Review [How search works in CPS](https://docs-v3-preview.elastic.dev/elastic/docs-content/tree/main/explore-analyze/cross-project-search/cross-project-search-search) for more information about how to build queries in a CPS context, including how to restrict search scope using qualified search expressions and project routing.