Sync a secret from a source
Create a secret from a 1Password or Vault reference, choose the source when several can reach it, and refresh it on demand.
A synced secret's value comes from a reference: op://<vault>/<item>/<field> (or
op://<vault>/<item>/<section>/<field>) for 1Password, vault://<mount>/<path>#<key> for Vault.
Replace OPENAI_API_KEY with the secret's name and 5b8c1d2e-3f4a-4b6c-8d7e-9f0a1b2c3d4e with its
id.
Prerequisites
- A connected source; see Connect 1Password or Connect HashiCorp Vault or OpenBao.
- Permission for
secrets:CreateSecret, andsecrets:UseSecretSourceon the source (on every source the platform has to ask which vaults it reaches). To refresh,secrets:SyncSecret. - An enabled KMS key.
Create a synced secret
The Create secret form takes a value only. Import references for an app with a .env.op file
instead; see Import a .env file.
dcloud secrets secrets create --name OPENAI_API_KEY \
--key-id 1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d \
--reference '{"ref":"op://Production/OpenAI/credential","source":"prod-1password"}'POST /secrets/api/secrets
{ "name": "OPENAI_API_KEY", "keyId": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "reference": { "ref": "op://Production/OpenAI/credential", "source": "prod-1password" } }The reference must resolve now, so a synced secret always has a value. Without a group, it is
filed under the reference's path, with words that name an environment dropped: for 1Password the
vault and item (op://Production/OpenAI/credential → openai), for Vault the mount and the path
without its last segment (vault://secret/shop/staging/db#password → secret/shop). See File secrets in groups.
Which source is used
source (by name) or sourceId chooses the source. Without one:
- with one source of that kind connected, it is used;
- if exactly one source's credential reaches the vault the reference names, it is used;
- if several can, or one could not be checked, the create is refused with
409, naming the sources; name the one to use; - if none can, the refusal names the vault and the sources checked.
A synced secret keeps syncing through its source however many are connected later.
Refresh
A synced secret is refreshed:
- on the source's schedule (every 60 minutes unless set otherwise; due sources are checked every five minutes). A changed value becomes a new version; an unchanged one writes nothing, so the versions record when the value changed upstream. The interval counts from the source's last sync of any kind, and a rollout or a Sync now on one secret counts too: it postpones the scheduled sync of the source's other secrets;
- at every app rollout that binds it, just before the environment is built;
- on demand: Sync now in the secret's panel or row menu, or on the source.
dcloud secrets secrets sync 5b8c1d2e-3f4a-4b6c-8d7e-9f0a1b2c3d4eA reference that fails keeps its last value and shows the error on the secret (Sync failed in the list). If the whole source fails, every secret keeps its last value and the source shows the error. A synced secret cannot be rotated or rolled back by hand: change it in the source and sync.
To try references without creating anything, POST /secrets/api/sources/{id}/check with
{ "references": [...] } answers ok or the error for each, never a value.
Refusals
422"… did not resolve: …", naming the reference and why, such as "item not found in that vault".502when the source itself fails, prefixed with the source's name.409"OPENAI_KEY already syncs that reference", naming the secret that already syncs it through that source. This holds in any environment: a create cannot add a second secret for a reference that one already syncs through that source.409"This secret is not synced from a source" (sync).409"No 1Password source is connected — connect one under Secrets → Sources".409"The source "prod-vault" is not a 1Password source", whensourcenames a source of the other kind.400"Unrecognised reference scheme: expected op://… or vault://…".404"Secret source not found" for an unknownsource.404"Key not found",409"Key is not enabled",400"Key must be an encrypt_decrypt key".