Skip to content

References and imports

Two features let you avoid copying the same value into many places. A reference puts one secret inside another secret’s value. An import makes the secrets of one folder appear in another folder.

A value can contain references to other secrets:

Syntax Refers to
${KEY} KEY in the same environment and folder
${prod:/KEY} KEY in the root folder of the prod environment
${prod:/db/PASSWORD} PASSWORD in the /db folder of prod
$${ A literal ${

Example: DATABASE_URL = postgres://app:${prod:/db/PASSWORD}@db.internal:5432/app.

  • Anything that starts with ${ but does not match the syntax is kept as literal text.
  • The stored value keeps the reference. Reads expand it only when asked: the API with expand=true; the CLI expands by default in secrets get, run and export (--no-expand turns it off); the dashboard shows the stored value and the resolved value side by side.
  • References can point to secrets that themselves contain references, up to 5 hops. A cycle, a reference to a secret that does not exist, or a chain deeper than 5 is a 400 that names the reference. See Limits for the size caps.
  • Every hop is authorized. To expand ${prod:/db/PASSWORD} you need read access to prod:/db. If you do not have it, the read is a 403 that names the reference, whether the target exists or not. A service token scoped to staging cannot read prod through a reference.
  • Changing the referenced secret changes every value that references it, on the next read.
  • The audit event of a read lists the secrets its references loaded.
  • Only string values expand. A typed value (json, pem, number, boolean, list) is always returned literally, so it cannot change shape after it was validated. A string may still reference a typed secret and gets that secret’s stored text, so http://h:${PORT} with a number PORT of 8080 expands to http://h:8080.
  • A non-sensitive value listed without reveal is returned as stored, never expanded, so a non-sensitive ${DB_PASSWORD} cannot leak the password it points to.

An import makes a folder show the secrets of another folder, in the same or another environment of the same project. For example, import shared:/ into prod:/api so every service gets the common values without copying them.

  • Manage imports on the folder in the dashboard (Add import), with the CLI (anchor imports), or through the API (/imports). Creating or deleting one requires write access to the folder and read access to the source.
  • Reads include imports only when asked: the API with includeImports=true; the CLI always includes them in secrets get, run and export; the dashboard lists imported secrets with an Imported from label.
  • Local secrets win. A key defined in the folder itself hides an imported key with the same name. Between imports, the first one added wins.
  • Imports are not followed transitively: importing a folder brings its own secrets, not the secrets that folder imports.
  • A reference inside an imported value resolves relative to the folder it comes from.
  • A listing authorizes every import: if you cannot read one source, listing the folder with imports is a 403 that names it. Reading one key that exists locally still works.
  • Deleting an environment removes the imports that point to it.

An import is a live link, not a copy: every read looks at the source folder again.

  • A key added to the source, or a new value of one of its keys, shows up in the importing folder on the next read: the dashboard after a reload, anchor secrets get, run and export.
  • It does not show up when the importing folder has a key with the same name (local keys win), or when an earlier import of the same folder already has that key.
  • Only the source folder itself is imported: importing shared:/ brings neither shared:/db nor the folders shared:/ imports.
  • A running anchor run keeps the environment it started with. Restart it, or start it with --watch to restart on changes.
  • A file written by anchor export is a snapshot. Export again to pick up changes.
  • A service token reading the importing folder also needs read access to the source folder.