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.

Last updated 18 November 2026View as Markdown

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, and secrets:UseSecretSource on 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.

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-9f0a1b2c3d4e

A 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".
  • 502 when 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", when source names a source of the other kind.
  • 400 "Unrecognised reference scheme: expected op://… or vault://…".
  • 404 "Secret source not found" for an unknown source.
  • 404 "Key not found", 409 "Key is not enabled", 400 "Key must be an encrypt_decrypt key".
Did this page help you?