A secret is an encrypted value (a password, API key, or token) stored once and then referenced from one or more connections, instead of typing the same credential directly into every connection that needs it. This keeps the raw value out of connection configuration screens, exports, and support packages.
Before you begin#
- Access to Settings → Secrets (requires the
secrets system-administration permission).
Create a secret#
- Open Settings → Secrets and select Create Secret.
- Enter a Label to identify it later, and choose a Type (Password or Other).
- Enter the Secret Value.
- Select Create.
Once created, the value is never sent back to the browser again in plain form: there's no "reveal" action anywhere in the UI, for anyone, regardless of permission. If you need to confirm what a secret's value actually is, you'll need to check wherever you originally recorded it; Buttons itself won't show it to you again.
Bind a connection field to a secret#
- Open the connection's configuration.
- Next to the field you want to protect, select the key icon labeled Use secret.
- Choose an existing secret from the list, or select Create secret from within the picker if you need a new one.
Once bound, the field no longer shows a text input at all, just the secret's label and type, with a dropdown to switch to a different secret, an Edit secret shortcut, and a way to clear the binding. Someone without the secrets permission sees only "Secret configured (no permission to view or change)" for an already-bound field, or "No permission to select secrets" if it isn't bound yet: they can't see or set the underlying value either way.
Rotate a secret's value#
Open the secret (from Settings → Secrets, or via Edit secret on any field that uses it) and enter a New Value: leaving it blank keeps the current value unchanged. Saving immediately pushes the new value to every connected module currently using it, without needing to re-save each connection individually. Every connection field bound to this secret keeps working through the change automatically; nothing needs to be re-bound.
See what's using a secret#
A secret's own detail page lists every connection currently bound to it, under Used by Connections: useful before editing or deleting one you're not sure is still in use.
Delete a secret#
Deleting a secret is immediate and isn't blocked even if connections are still bound to it.
Warning
Buttons does not warn you or stop you from deleting a secret that's still in use. Check Used by Connections on the secret's detail page first. A connection field left pointing at a deleted secret shows "Secret not found" in the UI, and the connection itself receives an empty value for that field at runtime, effectively losing that credential silently until you bind it to something else.
Understand backup and export behavior#
Unchecking Include secrets during a configuration export or scheduled backup removes only the stored values in the secret table: connections that reference a secret keep that reference in the exported archive rather than having it stripped or blanked out. If you later import that archive somewhere the referenced secrets don't exist, every field that depended on one shows "Secret not found" again, the same as if the secret had been deleted.
Note
The encryption key that protects every secret's value is stored in the same database as the secrets themselves, and it's included in every export or backup regardless of whether Include secrets is checked. Excluding secrets keeps the values out of that specific archive, but doesn't change who could decrypt a full database dump obtained some other way. Treat full database access as equivalent to secret access.
If you get stuck#
What you see | What to try |
|---|
You need to check what value a secret actually holds. | There's no way to reveal it in Buttons: check wherever the value was originally recorded, or issue a new one if that's not available. |
A connection field shows "Secret not found." | The bound secret was deleted, or this archive was imported without secret values: check Settings → Secrets, and re-bind the field to a valid secret. |
You're not sure whether it's safe to delete a secret. | Open the secret and check Used by Connections first: deletion isn't blocked even if it's still in use. |
A field shows "No permission to select secrets." | Binding a secret requires the same secrets permission as managing secrets outright: there's no separate lower-level permission just to select one. |
You updated a secret's value and expect connections to need re-saving. | They don't: an update pushes the new value to every bound connection immediately, with no re-binding required. |
Where to go next#
