When you connect Ballet to the tools your team relies on, such as a CRM, a help desk, a payments API or your own internal service, you trust us with the keys to those systems: API keys, bearer tokens and passwords.
This article explains what Ballet does with those credentials once you save them, and why you can safely open, share and edit a connection without exposing them.
In short, Ballet follows three rules:
Once you save a credential, Ballet never sends it back out. Wherever the connection appears, the secret is replaced with a mask:
Every one of these views goes through the same masking step, so a new screen or integration can't accidentally show more than the others.
Masking still leaves the configuration readable:
Authorization: Bearer ••••••••, so you know it's a bearer token without seeing the token.Content-Type or Accept aren't secret, so Ballet shows them as they are. Anything Ballet doesn't recognise as safe is masked by default.{{CRM_API_KEY}} is only the name of a secret, so it's safe to show (see section 5).Say you open a connection to change the URL path or a timeout. The credential field shows dots, and you leave it alone. When you click Save, Ballet recognises the untouched mask and keeps the credential it already has.
The secret is never sent back to your browser to make this work. You don't have to retype it, and nobody editing the connection ever needs to know it.
Ballet only keeps the saved credential when the field is exactly as it was shown. If you type anything into it, Ballet treats that as a new value rather than guessing what you meant.
Sometimes a masked value can't be matched to a saved credential. For example:
X-Api-Key became X-API-TokenIn these cases Ballet doesn't save the change, and it doesn't quietly drop or blank the field either. You get a clear message that names the field and asks you to re-enter the credential or use a secret reference.
Nothing is half-saved, and your integration never breaks silently later. The same rule applies whether you make the change in Studio, through the API or through an AI agent.
Because Ballet puts saved credentials back into requests for you, it also checks where those requests are going.
Each saved credential is tied to the address it was saved with: the scheme, host and port, such as https://api.vendor.com. Ballet only uses it for requests to that same address.
/v2/orders to /v2/customers, works as normal.{subdomain}.vendor.com match exactly one subdomain, so acme.vendor.com is allowed and vendor.com.evil.io is not.This adds another layer of protection on top of access controls. Even someone who is allowed to edit a connection can't use it to send your saved key somewhere else.
The safest credential is one that is never written into a connection at all. Ballet lets you keep credentials in your workspace secrets and refer to them by name:
Authorization: Bearer {{CRM_API_KEY}}
(${CRM_API_KEY} works too.)
With a reference:
If you paste something into a header that looks like a raw token, Studio shows a gentle hint that suggests a secret reference instead. The hint is announced to screen readers alongside the field it describes.
| When you… | Ballet… |
|---|---|
| Open or list a connection anywhere (Studio, agents, MCP, shares) | Shows a mask, never the credential |
| Save without touching the credential | Keeps the saved credential |
| Rename the field or change the auth type | Stops the save and asks you to re-enter it |
| Test or send a request to the same host | Uses the saved credential |
| Send a request to a different host | Refuses to attach the saved credential |
| Move a connection to a new host | Asks you to enter the credential again |
Use {{SECRET_NAME}} | Fills in the value on the server only when the request is sent |
Have questions about how Ballet handles your data? Reach out to our team. We're happy to go into more detail.