> ## Documentation Index
> Fetch the complete documentation index at: https://infisical.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Secret referencing and importing

> Learn the fundamentals of secret referencing and importing in Infisical.

The short video below walks through secret referencing and importing, covering how to reuse a "base" secret's value across others and how to pull secrets from another environment or folder into the current context.

[YouTube video player](https://www.youtube.com/embed/GMcblYp34t0)

## Secret referencing

Infisical's secret referencing functionality makes it possible to reference the value of a "base" secret when defining the value of another secret.
This means that updating the value of a base secret propagates directly to other secrets whose values depend on the base secret.

![Secrets dashboard with values revealed, showing references highlighted inside them](https://mintlify.s3.us-west-1.amazonaws.com/infisical/images/platform/secret-references-imports/secret-reference.png)

Since secret referencing reconstructs values on the client side, any client (user, service token, or machine identity) fetching secrets must have proper permissions to access all base and dependent secrets. Without sufficient permissions, secret references won't resolve to their appropriate values.

For example, if secret A references values from secrets B and C located in different scopes, the client must have read access to all three scopes containing secrets A, B, and C. If permission to any referenced secret is missing, the reference will remain unresolved, potentially causing application errors or unexpected behavior.

This is an important security consideration when planning your secret access strategy, especially when working with cross-environment or cross-folder references.

> [!TIP]
>
> Hold `Cmd` (Mac) or `Ctrl` (Windows/Linux) and select a reference to jump to the secret it points at.

### Syntax

When defining a secret reference, interpolation syntax is used to define references to secrets in other environments and [folders](https://infisical.com/docs/documentation/platform/folder.md).

Suppose you have some secret `MY_SECRET` at the root of some environment and want to reference part of its value from another base secret `BASE_SECRET` located elsewhere.
Then consider the following scenarios:

* If `BASE_SECRET` is in the same environment and folder as `MY_SECRET`, then you'd reference it using `${BASE_SECRET}`.
* If `BASE_SECRET` is at the root of another environment with the slug `dev`, then you'd reference it using `${dev.MY_SECRET}`.

Here are a few more helpful examples for how to reference secrets in different contexts:

| Reference syntax | Environment | Folder | Secret Key |
| - | - | - | - |
| `${KEY1}` | same env | same folder | KEY1 |
| `${dev.KEY2}` | `dev` | `/` (root of dev environment) | KEY2 |
| `${prod.frontend.KEY2}` | `prod` | `/frontend` | KEY2 |

## Secret imports

Infisical's Secret Imports functionality makes it possible to import the secrets from another environment or folder into the current folder context.
This can be useful if you have common secrets that need to be available across multiple environments/folders.

To add a secret import, select **Add New**, then select **Import Secrets**.

![Add Secret Import dialog](https://mintlify.s3.us-west-1.amazonaws.com/infisical/images/platform/secret-references-imports/secret-import-add.png)

Each import appears above the secrets on the dashboard, labeled with the environment and path it pulls from. In the example below, `/backend` and `/third-party` are both imported into the current folder.

![Secrets dashboard listing two imports above the secrets](https://mintlify.s3.us-west-1.amazonaws.com/infisical/images/platform/secret-references-imports/secret-import-added.png)

Hover over an import to reach its controls: select the trash icon on the right to delete it, or drag the handle on the left to reorder it.

![An import row hovered, showing the drag handle and the trash icon](https://mintlify.s3.us-west-1.amazonaws.com/infisical/images/platform/secret-references-imports/secret-import-delete.png)

Order matters. If two imports carry a secret with the same name, the value from the bottom-most import wins.

## Relative reference resolution in imported secrets

> [!NOTE]
>
> Only available on the **V4 Secrets API** (`/api/v4/secrets`). v3 and below always resolve local references against the source environment.

When you import secrets from one environment into another, the imported secrets may contain references like `${KEY}` that point to other secrets. **Relative resolution** changes how those local references are looked up:

| Reference type | Behavior |
| - | - |
| `${KEY}` (local) | Current env first, source env as fallback |
| `${env.path.KEY}` (absolute) | Always resolves against the specified env |

Resolution order for `${KEY}` inside an imported secret *(e.g. staging imports from dev)*:

1. Look in `staging` (current environment)
2. If not found, look in `dev` (source environment)
3. If still not found, expand to an empty string

This lets you override any imported key simply by defining it in the destination environment.

### Example

```
dev:
  DB_HOST = "dev-db.internal"
  DB_URL  = "postgres://${DB_HOST}/myapp"

staging imports from dev:
  DB_HOST = "stg-db.internal"
```

Fetching staging's imported `DB_URL` via v4 → `postgres://stg-db.internal/myapp`

The `${DB_HOST}` local reference resolves to staging's value. Without relative resolution (v3), it would resolve to dev's `DB_HOST` instead.

### Behavior notes

* **The current-env-first rule applies at every depth of recursive expansion**, not just the top level. If an imported secret references another secret that references another, each `${KEY}` at every level checks the current environment first.
* **Import-chain lookup**: when looking for a key in an environment, Infisical also searches that environment's one-level-deep imports. If prod imports from `/shared` and `/shared` has `KEY`, a `${KEY}` reference in a prod context will find it.
* **Permissions**: read access is enforced at every step. If the calling identity lacks access to any secret in the chain, the request returns `403`.

> [!WARNING]
>
> Only one level of imports is searched during reference expansion. If prod imports `/shared`, and `/shared` imports `/base`, secrets in `/base` aren't visible.

## Cross-project secret sharing

> [!NOTE]
>
> Cross-project secret sharing is a paid feature.
>
> If you're using Infisical Cloud, then it's available under the **Pro Tier**. If you're self-hosting Infisical,
> then you should contact [sales@infisical.com](mailto:sales@infisical.com) to purchase an enterprise license to use it.

Cross-project secret sharing allows secrets to be referenced or imported across different projects within the same organization. This is useful when multiple projects share common infrastructure secrets (such as database hosts, API keys, or service URLs) without duplicating them.

### Enabling cross-project secret sharing

Cross-project sharing is controlled by an organization-level toggle. An organization admin must enable it before any cross-project references or imports can be created:

1. Go to the **Secrets Management** product page.

   ![The Secrets Management product page](https://mintlify.s3.us-west-1.amazonaws.com/infisical/images/platform/secret-references-imports/01-secrets-management.png)
2. Select **Product Settings**.

   ![The Product Settings page](https://mintlify.s3.us-west-1.amazonaws.com/infisical/images/platform/secret-references-imports/02-product-settings.png)
3. Turn on **Cross-project secret sharing**.

   ![Product Settings with the cross-project secret sharing toggle on](https://mintlify.s3.us-west-1.amazonaws.com/infisical/images/platform/secret-references-imports/03-enable-secret-sharing.png)

When this toggle is disabled, all cross-project references resolve to empty strings and cross-project imports are ignored.

### Project grants

A Project Grant is the authorization mechanism that controls which projects can access secrets from a given source project. Grants are created from the **source project** (the project that owns the secrets) and specify:

* **Source environment and folder path**: the specific location in the source project being shared.
* **Target project**: the project that is allowed to reference or import secrets from that location.

The key benefit of project grants is that **users in the target project don't need any permissions in the source project**. As long as a grant exists from the source project to the target project for a given folder, users in the target project can create cross-project references and imports for that folder.

To create a new grant:

1. Go to **Project Settings** in the source project.

   ![Project settings for the source project](https://mintlify.s3.us-west-1.amazonaws.com/infisical/images/platform/secret-references-imports/04-project-settings.png)
2. Select the **Policies** tab.

   ![The Policies tab, showing the Cross-Project Secret Sharing section](https://mintlify.s3.us-west-1.amazonaws.com/infisical/images/platform/secret-references-imports/05-project-policies.png)
3. Under **Cross-Project Secret Sharing**, select **Share Secrets**.

   ![The Cross-Project Secret Sharing section with no linked projects yet](https://mintlify.s3.us-west-1.amazonaws.com/infisical/images/platform/secret-references-imports/06-create-project-grant.png)
4. Under **Environments & folders**, choose the environment to share from, then type a folder path and select **Add**. Under **Share with projects**, choose the project that should get access, then select **Share**.

   ![The Share Secrets panel with an environment, a folder, and a target project chosen](https://mintlify.s3.us-west-1.amazonaws.com/infisical/images/platform/secret-references-imports/07-share-project-grant.png)

### Cross-project references

You can reference secrets from a different project using the `@project-slug` prefix. This allows you to compose secret values across projects without duplicating them.

| Reference syntax | Project slug | Environment | Folder | Secret Key |
| - | - | - | - | - |
| `${@backend-api.prod.KEY1}` | `backend-api` | `prod` | `/` (root) | KEY1 |
| `${@backend-api.dev.database.DB_HOST}` | `backend-api` | `dev` | `/database` | DB\_HOST |

> [!WARNING]
>
> Cross-project references **aren't recursively expanded**. If the referenced secret in the source project itself contains a cross-project reference to yet another project, that nested reference won't be resolved. Only same-project references within the source secret are expanded.

### Cross-project imports

You can also import secrets from a different project entirely. Cross-project imports work the same way as regular imports, but the source environment and folder belong to another project within the same organization.

To create a cross-project import:

1. Select **Add New**, then select **Import Secrets**.

   ![The Add New menu, showing Import Secrets](https://mintlify.s3.us-west-1.amazonaws.com/infisical/images/platform/secret-references-imports/08-add-secret-import.png)
2. Select **Another Project**.

   ![The Add Secret Import dialog with Another Project selected](https://mintlify.s3.us-west-1.amazonaws.com/infisical/images/platform/secret-references-imports/09-other-project.png)
3. Choose the source **Project**, **Environment**, and **Folder path**, then select **Create Import**.

   ![The dialog filled in with a source project, environment, and folder](https://mintlify.s3.us-west-1.amazonaws.com/infisical/images/platform/secret-references-imports/10-create-import.png)
4. The import appears at the top of the secrets dashboard, labeled with the project it pulls from.

   ![The secrets dashboard showing the new cross-project import](https://mintlify.s3.us-west-1.amazonaws.com/infisical/images/platform/secret-references-imports/11-created-secret-import.png)

> [!WARNING]
>
> Cross-project imports **aren't transitive**. If the source folder in the foreign project has its own cross-project imports (pointing to a third project, or back to the original project), those nested cross-project imports won't be followed. Only imports that stay within the same source project are resolved recursively.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.