Connector secrets
A connector uses secrets for the passwords, tokens and keys its connection needs. This page explains the vault that stores them, how a stored value behaves from then on, and what to do when the connector reports a missing secret.
Store a secret
- Open the connector and go to its Secrets section. On a custom connector's Connection step, click Manage Secrets to open the Secrets Vault.
- Click Add secret and enter a name and a value.
- Click Save in the vault. The name and the value are stored together; nothing is stored before you save.
- Click Copy reference next to the secret and paste the reference in place of the value in the configuration. The reference has the form
{{secret:NAME}}. For a custom connector's configuration, see Configure a custom connector.
The connector then uses the stored value when it tests the connection and when it loads data.
Name a secret after the setting it fills: in a custom connector, the setting's full dotted path, such as auth_token or oauth_credentials.client_secret. Names run up to 200 characters and use letters, digits, underscores and dots, starting with a letter, a digit or an underscore. A value runs up to 8192 characters.
Vault actions
| Action | What it does |
|---|
| Add secret | Adds a name and a value. The secret is stored when you click Save. |
| Replace | Types a new value for a stored secret. |
| Clear | Removes a secret after you confirm; the confirmation reads "Clear this secret?" and "This cannot be undone.". It is disabled while the configuration still refers to the secret. |
| Copy reference | Copies the reference ({{secret:NAME}}) that the configuration uses to point at the secret. |
| Move to Secrets | Appears when the configuration holds a value inline: "{path} holds an inline value. Move it to the Secrets panel and reference it as {{secret:name}}?". It stores the value and replaces it with a reference. The configuration change stays unsaved until you save it. |
A value that also appears literally in the configuration must be removed there before it can be stored as a secret, and a secret set that is too large is refused before saving.
What a saved value shows
- The vault lists secrets by name. A stored value reads back as a mask (
------------), never as the value itself.
- No screen shows a value again, not even to the person who stored it. Keep your own copy; to change it, use Replace.
- The vault exists from the moment the connector is created, before it is installed.
- The Secrets section summarises the vault: it reads Vault is empty, or reports how many secrets are stored; an empty connector reads "Nothing is stored in this connector's Secrets vault yet.".
Change or remove a secret
- To change a value, click Replace beside the secret, type the new value and save. The connector uses the new value from then on. If the service refuses the old value, for example after a failed sign-in, replacing it is the fix.
- Some connections keep the previous value during a changeover window: the old value stays accepted until you stop it, and an ordinary save keeps it rather than dropping it. For a webhook, follow Rotate a webhook secret.
- To remove a value, click Clear and confirm. While the configuration still refers to the name, Clear stays disabled; stop referring to it and save first.
When a secret is missing or refused
- If the configuration refers to a name with no stored value, the save or the sync is refused before anything runs, and the message names the secret: references secret(s) that are not set: followed by the names. Store each value in the Secrets section, then save or sync again. A reference without a value is also shown there as "{path} references secret {secret}, which is not stored.", with Add "…" and Edit config beside it.
- A delete for a name with no stored value answers is not set; there is nothing to remove.
Secrets in a connector chat
- The connector agent can read the stored secret names and the wiring report, which shows the setting each stored name binds and what is still missing, but never a value.
- When the agent needs a value, it asks you to store it in the connector's Secrets section and waits. The chat shows Waiting for user to store secret(s) in the Secrets panel. Requested: followed by the names. Store the values, then send the next message.
- On a Connect Any API connector, the agent points you to the connection form instead of taking a value in the chat. See Connect any API.
- If you paste a credential into the chat, it is moved into the vault, erased from the stored conversation and replaced with a
<redacted:NAME> marker. Markers and placeholders are not values, so store credentials in the vault rather than pasting them.
- A secret stored under the wrong name is fixed by renaming it, never by storing it again; the value is kept. The chat confirms: Renamed vault secret "from" to "to"; the value was kept.
- When the service refuses a stored value, the agent asks for that name again so you can replace it in the panel.
Who can manage secrets
- Storing or clearing a connector's secrets needs Add/Modify Lake Objects. See Who can do what in the Lake.
- With the view permission alone, you can open the vault and read secret names, but not set or delete them; the vault tells you that you have view-only access.
- The agent never asks for a secret value in the chat; it asks you to store the value in the Secrets section.
Duplicates
- Duplicating a connector keeps the connection's stored password but copies none of its vault secrets.
- The copy starts with an empty vault, so store the secret values again on the copy.
Questions, answered
Why can nobody, including me, read a saved value again?
Values are write-only. A stored value reads back as a mask (------------), and no screen or chat result shows the value itself. Keep your own copy when you store it; to change it, use Replace.
How do I replace a stored secret?
Open the connector's Secrets section, click Replace beside the secret, type the new value and save. The connector uses the new value from then on. If the connection keeps a changeover window, the old value stays accepted until you stop it; see Webhook and RabbitMQ.
Why is Clear disabled on a secret?
Because the configuration still refers to the secret. Update the configuration to stop using the name, save, then click Clear.
What happens to secrets when I duplicate a connector?
The copy keeps the connection's stored password but none of the vault secrets, and its vault starts empty. Store the values again on the copy.
The connector agent asks me to store a secret. Where do I put it?
In the connector's Secrets section. On a custom connector, Manage Secrets opens the Secrets Vault; for the connector end to end, see Connect Anything (custom connector). Store the value there and send the next message; the chat waits until you do. The chat does not take the value itself.
I pasted a credential into the chat. Can anyone still read it there?
No. The value is moved into the vault, erased from the stored conversation, and replaced with a <redacted:NAME> marker. The marker is not the value and cannot be used as one.
A stored secret is reported as not bound to any setting. How do I fix it?
Rename it to the setting's own name, its dotted path such as auth_token; the value is kept, and you never need to store it again. Names use letters, digits, underscores and dots, up to 200 characters.
I can open the vault but cannot add or remove secrets. Why?
You have view-only access. Reading secret names needs a view permission; setting and deleting them needs Add/Modify Lake Objects. Ask your administrator to add it to your role. See Who can do what in the Lake.