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.
References
Section titled “References”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 insecrets get,runandexport(--no-expandturns 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
400that names the reference. See Limits for the size caps. - Every hop is authorized. To expand
${prod:/db/PASSWORD}you need read access toprod:/db. If you do not have it, the read is a403that names the reference, whether the target exists or not. A service token scoped tostagingcannot readprodthrough 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
stringvalues expand. A typed value (json,pem,number,boolean,list) is always returned literally, so it cannot change shape after it was validated. Astringmay still reference a typed secret and gets that secret’s stored text, sohttp://h:${PORT}with anumberPORTof8080expands tohttp://h:8080. - A non-sensitive value listed without
revealis returned as stored, never expanded, so a non-sensitive${DB_PASSWORD}cannot leak the password it points to.
Imports
Section titled “Imports”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 insecrets get,runandexport; 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
403that names it. Reading one key that exists locally still works. - Deleting an environment removes the imports that point to it.
When changes show up
Section titled “When changes show up”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,runandexport. - 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 neithershared:/dbnor the foldersshared:/imports. - A running
anchor runkeeps the environment it started with. Restart it, or start it with--watchto restart on changes. - A file written by
anchor exportis a snapshot. Export again to pick up changes. - A service token reading the importing folder also needs read access to the source folder.