Secrets

Quick Answer

Use this guide to declare secret slots, bind secret values, rotate credentials, and wire secret refs into triggers and steps.

This guide covers secret slots, secret refs, bindings, rotation, and how secrets
are consumed by triggers and steps.

Core concepts

Concept	Meaning
Secret ref	Secret value stored under a `:secret-ref` key.
Secret slot	Declared in `:requires` with `:type :secret`.
Binding contract	Bindings map slot to `:secret-ref`; secret value is stored separately.
Source control rule	Flow definitions must never embed secret values.

Deploy-key guard secret (release control)

Deploy-key guard uses a separate server-side secret for release protection.

Aspect	Value
What it protects	Guarded flow release/promotion paths (`flows release`, `flows promote`, and disabling `:deploy-key-required`).
Where it is defined	Breyta environment secret `BREYTA_FLOW_DEPLOY_KEY` (configured by platform/admin).
How CLI provides it	`--deploy-key "<value>"` or local/CI env `BREYTA_FLOW_DEPLOY_KEY` when running release commands.
Storage model	Global Breyta deployment secret, not a flow `:requires` slot, bindings secret, or connection.
Flow opt-in switch	`:deploy-key-required true` in flow definition metadata.

Notes:

Enabling :deploy-key-required true fails unless BREYTA_FLOW_DEPLOY_KEY is configured for the Breyta environment.
Keep this secret in CI/runtime secret manager and inject it per job/session.

Declare a secret slot

Always set an explicit :secret-ref on secret slots.

{:requires [{:slot :webhook-secret
             :type :secret
             :secret-ref :webhook-secret
             :label "Webhook Secret"}]}

Provide a secret value (configure)

Set the secret on the draft target:

breyta flows configure <slug> --set webhook-secret.secret="YOUR_SECRET_VALUE"

Generate a new secret value

Use :generate to create a secret value server-side:

{:bindings {:webhook-secret {:secret :generate}}}

Secret Lifecycle (CLI)

Stage	Command / action	Result
Bind value	`breyta flows configure <slug> --set <slot>.secret="VALUE"`	Stores secret under slot `:secret-ref`.
Generate value	`breyta flows configure <slug> --set <slot>.secret=:generate`	Server generates and stores secret value.
Rotate	Re-run `flows configure` with updated secret value	Replaces value under same `:secret-ref`.

Rotate a secret

Apply the new secret value with flows configure.
Re-run to store the new value under the same :secret-ref.
Update external systems to use the new secret.

breyta flows configure <slug> --set webhook-secret.secret="NEW_SECRET_VALUE"

Using secrets in webhook auth

Auth configs reference secrets via :secret-ref:

{:auth {:type :api-key
        :header "X-API-Key"
        :secret-ref :webhook-secret}}

Service account JSON secrets (Google APIs)

Some integrations need a full JSON service account key (not a single token string). Store the entire JSON payload as a secret value and reference it via :secret-ref.

Declare the slot:

{:requires [{:slot :google-drive-service-account
             :type :secret
             :secret-ref :google-drive-service-account
             :label "Google Drive service account JSON"}]}

Bind the value (prod):

{:bindings {:google-drive-service-account {:secret "<SERVICE_ACCOUNT_JSON>"}}}

Use it in an HTTP step auth block:

{:auth {:type :google-service-account
        :secret-ref :google-drive-service-account
        :scopes ["https://www.googleapis.com/auth/drive.readonly"
                 "https://www.googleapis.com/auth/drive.metadata.readonly"]}}

{:auth {:type :hmac-sha256
        :header "X-Signature"
        :secret-ref :webhook-secret}}

{:auth {:type :basic
        :username "webhook-user"
        :secret-ref :webhook-basic-password}}

Common mistakes

Mistake	Consequence
Omitting `:secret-ref` on secret slot	Validation/runtime binding failures.
Putting secret values in flow definitions	Secret leakage risk in source and review surfaces.
Mismatching trigger `:secret-ref` and slot `:secret-ref`	Auth checks fail at runtime.