---
component: ROOT
version: "2026.3"
slug: ROOT/administration/project-level-access-control
canonical_url: "https://docs.develocity.ai/2026.3/administration/access-control/project-level-access-control/"
title: "Project-Level Access Control"
description: "Restrict access to specific project data in Develocity with project-level access control, so teams see only the builds and data relevant to their projects."
keywords:
  - "permissions"
  - "developer"
status: current
---

<!-- llms-index: https://docs.develocity.ai/llms.txt -->

# Project-Level Access Control

<a id="preamble"></a>

Project-level access control isolates build data, cache entries, and acceleration features by project.

This ensures that sensitive build data is only visible to authorized users. It also prevents builds from one project from interfering with or accessing another project’s cache.

<a id="prerequisites"></a>

## Prerequisites

Before configuring project-level access control, ensure you have:

*   Administrator access to Develocity
    
*   The [Configure projects permission](https://docs.develocity.ai/2026.3/administration/access-control/permissions-and-roles/#configure-projects-permission) (not available to the system user account)
    
*   [Authenticated Build Access](https://docs.develocity.ai/2026.3/administration/access-control/identity-provider/#authenticated_build_access) configured if using Build Cache
    

<a id="core-concepts"></a>

## Core Concepts

*   **Projects:** The basic unit of isolation. Each build must identify itself with a **Project ID**.
    
*   **Project Groups:** A collection of projects. Project groups function like roles. When you assign a project group to a user, you grant that user access to all projects in the group.
    
*   **Build Isolation:** Builds associated with Project A can only read cache entries created by other Project A builds.
    

<a id="configuring-projects-and-groups"></a>

## Configuring Projects and Groups

To manage project access, you must first define the projects and the groups that contain them.

<a id="project_mode"></a>

### Create Projects

To create new projects, sign in as a user who has the [Configure projects permission](https://docs.develocity.ai/2026.3/administration/access-control/permissions-and-roles/#configure-projects-permission). You cannot create projects with the system user account.

1.  Navigate to **Administration**  **Access control**  **Projects**.
    
2.  Click **Add project**.
    
3.  Enter a **Display Name** and a **Project ID**.
    
    *   **Note:** The **Project ID** is what developers must use in their build configuration (Gradle, Maven, etc.).
        
    
4.  Click **Save**.
    

> [!NOTE]
> Projects cannot be deleted.

<a id="create-project-groups"></a>

### Create Project Groups

1.  On the same **Projects** tab, scroll to the **Project Groups** section.
    
2.  Click **Add project group**.
    
3.  Name the group (e.g., `Android-Team-Projects`) and select the projects to include.
    
4.  Click **Save**.
    

<a id="assign-groups-to-users"></a>

### Assign Groups to Users

Project groups are assigned to users just like Roles:

*   **Manual:** Go to **Administration**  **Access control**  **Users**, edit a user, and select the project groups.
    
*   **External:** Map project groups from SAML or LDAP groups in the **Identity Provider** settings.
    

> [!IMPORTANT]
> Applying the configuration updates the system services and can take several minutes to complete.

> [!TIP]
> Keep your configuration safe
> 
> Before making major changes to system settings, consider exporting your current configuration via **Administration**  **Import/export**.

> [!NOTE]
> The Test Distribution Administration page shows usage data for all projects, regardless of a user’s access.

Develocity stores projects and project groups in the application database, rather than in the Develocity configuration file. Use database backups to restore projects and project groups just as you would users, access keys, and other app [configuration data migrated](https://docs.develocity.ai/2026.3/operations/migrations/user-managed-database-migration/#data_to_be_migrated) with the database.

<a id="enabling-enforcement"></a>

## Enabling Enforcement

Develocity disables project-level access control by default. Configure your projects and groups before you turn on enforcement.

1.  Navigate to **Administration**  **Access control**  **Projects**.
    
2.  Check **Enable project-level access control**.
    
3.  Select **Save**.
    

Once you enable project-level access control, the "Allow data without an associated project" checkbox is displayed. This setting controls whether data without an associated project can be submitted to Develocity. The setting is enabled by default. Keep it enabled until every build specifies a project ID.

> [!NOTE]
> The "Allow data without an associated project" setting controls whether new data without project associations will be accepted by Develocity. The "Access all data without an associated project" permission controls users' access to that data, and the ability to submit it.

> [!WARNING]
> When project-level access control is enabled, builds that do not specify a project depend on the "Allow data without an associated project" setting. If that setting is disabled, those builds cannot publish a Build Scan or use Develocity features.

> [!WARNING]
> Build Cache Requirement: To use project-level access control with the Build Cache, you must use Authenticated Build Access for authentication. Standard credential-based authentication is not supported for per-project cache isolation.

> [!NOTE]
> Changes to access control settings can take up to 20 minutes to propagate through the various components of Develocity.

<a id="automated-management-api"></a>

## Automated Management (API)

> [!IMPORTANT]
> Project configuration using the Develocity API is in Beta and might change without notice in future releases.

For high-scale environments, you can automate project and group creation using the Develocity API. Use it to sync Develocity with an internal project registry.

For a complete list of project endpoints, see the [Develocity API Manual](https://docs.develocity.ai/2026.3/reference/develocity-api/). Managing projects via API requires the [Configure projects permission](https://docs.develocity.ai/2026.3/administration/access-control/permissions-and-roles/#configure-projects-permission).

<a id="short-lived-access-tokens"></a>

## Short-Lived Access Tokens

Develocity access keys are long-lived, creating risks if they are leaked. Instead, use short-lived access tokens to authenticate with Develocity. See the appropriate manual for your build tool for information on how to generate and use access tokens. Access tokens are only valid for the Develocity instance that created them.

> [!NOTE]
> Changing a Develocity instance’s hostname invalidates all existing access tokens.

Access tokens are signed JWTs, or [JSON Web Tokens](https://www.jwt.io/), and work like OAuth and OIDC access tokens. No central directory of access tokens manages their validity. Access token validity is based on their signature and associated signing key.

<a id="revoking-access-tokens"></a>

### Revoking Access Tokens

If an access token is leaked, you can use the `POST /api/auth/revoke-signing-keys` endpoint to revoke all existing access tokens.

> [!NOTE]
> See the [API documentation](https://docs.develocity.ai/2026.3/reference/develocity-api/) for more details on the `/api/auth/revoke-signing-keys` endpoint.

Using this endpoint requires the [Configure operational settings permission](https://docs.develocity.ai/2026.3/administration/access-control/permissions-and-roles/#configure-operational-settings-permission). The endpoint deletes any existing access token signing keys and creates a new one, which invalidates all existing access tokens. The operation takes a few minutes and does not affect access keys.

The signing keys used for access tokens are stored in Develocity’s database. They are automatically rotated every seven days. Rotation does not interrupt authentication.

<a id="how-to-use-in-your-build"></a>

## How to Use in Your Build

For enforcement to work, your build scripts must specify the Project ID. Refer to the specific build tool documentation for configuration details:

*   **Gradle:** See the [Develocity Gradle Plugin User Manual](https://docs.develocity.ai/gradle/4.6/gradle-plugin/#configuring-project-identifier)
    
*   **Apache Maven:** See the [Develocity Maven Extension User Manual](https://docs.develocity.ai/maven/2.6/maven-extension/#configuring-project-identifier)
    
*   **Bazel:** See the [Develocity Bazel Configuration Guide](https://docs.develocity.ai/bazel/bazel-config/#project-level-access-control)
    
*   **sbt:** See the [Develocity sbt Plugin User Manual](https://docs.develocity.ai/sbt/1.4/sbt-plugin/#configuring-project-identifier)