Secret Referencing and Importing

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.

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.

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 will not 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.

Syntax

When defining a secret reference, interpolation syntax is used to define references to secrets in other environments and folders.

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:

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.

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, press the downward chevron to the right of the Add Secret button; then press on the Add Import button.

Once added, a secret import will show up with a green import icon on the secrets dashboard. In the example below, you can see that the items in the path /some-folder are being imported into the current folder context.

To delete a secret import, hover over it and press the X button that appears on the right side.

Lastly, note that the order of secret imports matters. If two secret imports contain secrets with the same name, then the secret value from the bottom-most secret import is taken: "the last one wins."

To reorder a secret import, hover over it and drag the arrows handle to the position you want.

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.

When creating a cross-project import, you select the source project, environment, and folder path. The import will pull secrets from that location into your current folder context.

Cross-Project Secret Sharing

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. Navigate to the Secrets Management product page.
2. Navigate to Product Settings page.
3. Enable the Allow cross-project secret sharing option.

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 do not 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 manage project grants, navigate to the Project Settings in the source project and look for the Secret Sharing / Grants section.

Permissions

• Creating a grant requires the Create Grant permission on the Project Grant subject in the source project.
• Revoking a grant requires the Revoke Grant permission on the Project Grant subject in the source project.
• Creating a cross-project import in the target project only requires the standard Create permission on Secret Imports in that project. No permissions in the source project are needed.

Limitations

• No transitive cross-project imports: If Project A imports from Project B, and Project B itself has a cross-project import from Project C, the secrets from Project C will not appear in Project A. Only imports that stay within Project B are followed.
• No transitive cross-project references: If a secret in Project B contains a ${@project-c.prod.KEY} reference, that reference will not be resolved when Project A reads the secret through a cross-project reference or import. Only same-project references within the source secret are expanded.
• Same organization only: Cross-project sharing is limited to projects within the same organization.

Relative Reference Resolution in Imported Secrets

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:

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.