Secrets
Store API keys and tokens once in Settings > Secrets, give agents, workflows and connections access one secret at a time, and limit where each value can be sent.
Settings > Secrets is where you keep API keys, tokens and passwords that your agents, workflows and connections need. You save a value once. After that, nobody can read it back: not you, not an agent, not the API. You can replace it, and you decide who may use it and where it may be sent.
Add a secret
- Open Settings > Secrets and choose New secret.
- Give it a name in capitals with underscores, like
FACEBOOK_PAGE_TOKEN. - Paste the value. It is shown again only as dots.
- Under Allowed hosts, list the hosts the value may be sent to, like
graph.facebook.comor*.example.com. A secret with no hosts can't be sent over the network at all. - Under Access, add the agents, domains, workflows or connections that may use it. Nothing can use a secret until you give it access.
A secret belongs to the whole workspace. To use a different value in one environment, add an environment override with the same name on the secret's page.
Who can use a secret
| Who | How it uses the secret | Needs |
|---|---|---|
| An agent | secret:NAME as a header value in an HTTP call (adl_proxy_call) | Access for that agent or its domain, and the call's host in Allowed hosts |
| A workflow | ${{ secrets.NAME }} in an HTTP, notification or lookup node: the auth value, a header, the URL path or query, or the body | Access for that workflow, and the request's host in Allowed hosts |
| A connection (MCP server) | An environment value that is exactly ${{ secrets.NAME }} | Access for that connection; for a remote server, its host in Allowed hosts |
The value is added at the moment of the call. It never appears in an agent's
conversation, a prompt, a tool result or a log. If a service echoes the value
back, SchemaBounce replaces it with ***, including base64 and URL-encoded
copies.
A reference in a workflow is read only from the node's own settings, never from data passing through the workflow, so a payload can't pull a secret into a request.
Asking a person first
Each secret has a use policy:
- Runs when granted (the default). An agent or workflow with access, calling an allowed host, uses the secret without waiting. Giving access is the approval.
- Ask a person every time. Every call an agent makes with the secret waits in the Inbox until a person approves that exact call. Workflows and connections can't use a secret set to ask, because nobody is there to approve it mid-run.
A person's Require approval rule on a tool still always waits, whatever the secret says.
When an agent needs a secret
Agents can't create access for themselves. An agent can:
- List the secrets it has access to, with their hosts and policy, never the
values (
adl_list_secrets). - Request one it needs (
adl_request_secret). You get a notification linking to Settings > Secrets with the name and hosts filled in; you add the value there, so you never have to paste a token into a chat. - Store a value you already gave it (
adl_store_secret). That waits for a person to approve, then creates a secret only that agent can use.
Who can manage secrets
| Permission | Lets a person |
|---|---|
View Secrets (secrets:view) | See names, hosts, policy and who has access |
Manage Secrets (secrets:manage) | Add secrets, replace values, change hosts and policy, give and remove access, delete |
Owners, Admins and Operators have both by default. You can give either to a custom role on the Roles tab of Settings > Members.
Every change is recorded in the audit log: created, updated, replaced, deleted, access given, access removed, requested and used. The log names the secret, never its value.
Secrets you stored before
Secrets an agent stored before Settings > Secrets existed move there automatically. Each one keeps its hosts and is available only to the agent that stored it. Names are changed to capitals and underscores where needed.
Workflows that already used an environment secret, such as a workflow installed from the marketplace, keep working. Each one is given access to the secret it uses, and the host its step calls is added to the secret's Allowed hosts. This happens once. If you remove that access later, it stays removed, and the workflow's step fails until you give it back.
Installing a marketplace workflow that uses one of your secrets gives that workflow access to it, so installing one needs the Manage Secrets permission.
Common questions
Can I see a secret's value after I save it?
No. Values are write-only. To change one, replace it on the secret's page.
Why did a call that uses a secret fail?
The usual reasons are that the agent, workflow or connection hasn't been given access, the host it called isn't in the secret's Allowed hosts, or the secret is set to ask a person and the caller is a workflow or connection. A transform step on a pipeline route can't use a secret at all; move that step into a workflow. The error names the secret and the reason, never the value.
Does SchemaBounce staff see my secrets?
Values are encrypted with a key held in a key management service and are decrypted only at the moment a granted caller uses them. They are never shown in the console, the API, logs or the audit trail.
Related Documentation
Continue exploring