Secrets

Quick Answer

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

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

Core concepts

Deploy-key guard secret (release control)

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

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)

For human-entered secrets, prefer Breyta setup/connection UI secret fields and
do not ask for secrets in chat. Protected setup links should return through
login.

For automation or explicit CLI setup, 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)

After applying generated secrets, inspect the target profile/bindings metadata.
If a live profile still reports no secret bindings, configure the slot
explicitly:

breyta flows configure <slug> --target live --version latest --set webhook-secret.secret=:generate

Re-run breyta flows configure check <slug> --target live --version latest and
a live-shaped smoke test before trusting webhook auth or secret-backed steps.

Rotate a secret

1. Apply the new secret value with flows configure.
2. Re-run to store the new value under the same :secret-ref.
3. 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

Related

• Start Here
• Flow Authoring
• Flow Definition
• CLI Commands