Docs/Guides

Secrets

Sources need credentials: API keys, database passwords, signing keys. Synchronoid stores these as encrypted secrets, hands them to your steps only when a run needs them, and keeps them out of your code, your repository and your logs.

How secrets are stored

Values are encrypted at rest with a key per workspace, in the region where the workspace lives.
A value cannot be read back through the UI, the CLI or the API. You can only replace or delete it.
Workers receive a secret just before a step starts, and it is removed when the step ends.
Log lines and error messages are scanned, and known secret values are replaced with ***.

Never commit secretsDo not put a real value in synchronoid.yaml or in Python files. syn deploy refuses to deploy a project when it finds a string that looks like a live token, such as syn_live_.

Create and list secrets

terminal

$ syn secrets set REGISTRY_API_KEY --env prod
Value (input hidden):
Secret REGISTRY_API_KEY saved for env prod (version 1)

$ echo -n "$KEY" | syn secrets set REGISTRY_API_KEY --env dev --stdin
$ syn secrets list --env prod
NAME                VERSION  UPDATED               UPDATED BY
REGISTRY_API_KEY    1        2026-10-28 09:12 UTC  lena
KAFKA_PASSWORD      3        2026-10-02 14:40 UTC  tomas

You can also manage secrets in the control room under Settings, Secrets. Names use capital letters, digits and underscores.

Reference secrets in synchronoid.yaml

Use ${secret:NAME} wherever a value is needed. Synchronoid resolves the reference at run time, in the environment of the run.

synchronoid.yaml

sources:
  company_registry:
    connector: http_json
    base_url: https://registry.example.org/api
    auth:
      type: bearer
      token: ${secret:REGISTRY_API_KEY}
  warehouse:
    connector: postgresql
    dsn: postgresql://syn:${secret:WAREHOUSE_PASSWORD}@db.internal:5432/analytics

In Python, read a secret from the context. Use it only inside a step, not at import time.

pipelines/enrich.py

@sy.step
def call_scoring_api(ctx, payload):
    key = ctx.secret("SCORING_API_KEY")
    ctx.log.info("calling scoring API")       # never log the key
    return post(payload, headers={"X-Api-Key": key})

Environment scoping

A secret exists in one environment: dev, staging, prod or one you define. The same name can hold a different value in each. Code and configuration stay identical, and the run picks the value for its environment.

Environment	Typical use	Who can read at run time
`dev`	Local `syn dev` and test runs	Your runs only
`staging`	Pre-production deploys	Runs in the staging environment
`prod`	Scheduled and sensor runs	Runs in the prod environment

Only workspace admins can change prod secrets. Members can change dev secrets. If a reference has no value in the current environment, the run fails before any step starts with error SYN-3012.

Set the environment for local work with syn dev --env dev, and for a deploy with syn deploy --env prod.

Rotate a secret

Rotation does not need downtime, because every set creates a new version and each run reads the latest version when it starts.

Create the new key at the provider. Keep the old one active.
Run syn secrets set REGISTRY_API_KEY --env prod with the new value.
Check that a run starts and succeeds: syn runs list --limit 3.
Revoke the old key at the provider.

Runs that are already in progress keep the version they started with. If something goes wrong, restore the earlier value with syn secrets rollback REGISTRY_API_KEY --env prod --to 1. Versions are kept for 30 days.

Rotate on a scheduleAdd an alert rule for "secret older than 90 days" to be reminded. See Alerts.

Access to secrets

Every create, update, rollback and delete is written to the workspace audit log with the user, time and version, never the value. Audit logs are available on the Enterprise plan. For how Synchronoid protects data, see Security.