# 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](connect-1password.md) or
  [Connect HashiCorp Vault or OpenBao](connect-vault.md).
- 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

**Console**
The **Create secret** form takes a value only. Import references for an app with a `.env.op` file
instead; see [Import a .env file](/docs/deploy/guide/import-a-env-file).

**CLI**
```sh
dcloud secrets secrets create --name OPENAI_API_KEY \
  --key-id 1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d \
  --reference '{"ref":"op://Production/OpenAI/credential","source":"prod-1password"}'
```

**API**
```http
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](file-secrets-in-groups.md).

## 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.

```sh
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".

## Related

- [Manage a source](manage-a-source.md)
- `secrets.secrets.create` · `secrets.secrets.sync` · `secrets.sources.check`
