Managing connections
Edit and rotate connections, point live deployments at a different connection, and delete connections safely.
Connections outlive the work that uses them. This page covers what happens after you create one: changing it, swapping which connection a live deployment uses, and removing it.
Editing a connection
Open the connection's type under Studio → Connections, then choose Edit from the connection's … menu.
- Credentials are never shown again: secret fields read
••••••••. For a connection that authenticates with an API key, leave the key blank to keep it, or type a new one. For a username and password (Postgres) or an access key (S3), re-enter all the credential fields whenever you edit the connection — what you enter replaces what's stored. - Provider connections ask for the API key again, because the Authentication step uses it to list models. Saving checks the connection again and re-records its model's capabilities.
- Integration connections aren't re-checked when you save an edit.
Changes take effect for everything that uses the connection at once — drafts, tests, chat, and live deployments.
Rotating credentials
To rotate a key or password, edit the connection and enter the new secret. Every agent, workflow, and dataset points at the connection rather than at the secret, so there's nothing else to update.
Swapping the connection a deployment uses
What you build names a connection as its default — the model connection on an agent, the connection on an Integration node. A deployment can override that: point a live deployment's model or integration at a different connection in the same project, and it takes effect on the next execution — without editing the workflow or deploying a new version.
That's how the same deployed work is pointed at production credentials in one place and test credentials in another, and how you move a live agent to a new model connection without redeploying. Only connections that fit are offered: the same integration type, or a provider connection with the capability the slot needs.
Deleting a connection
Choose Delete from the connection's … menu. Compass first checks whether anything still uses it.
- Not in use — you're asked to confirm: the connection and its stored credentials are permanently deleted.
- In use — a Can't delete this connection dialog lists everything that still depends on it, so you can remove those references first.
A connection counts as in use when any of these reference it:
| What | When it counts |
|---|---|
| Workflows and agents | Their draft uses it, a live deployment's version uses it, or a deployment is bound to it. Each is marked Draft or Deployed and links to the builder. Old versions that nothing deploys don't count. |
| Datasets | A dataset embeds with it, its pipeline uses it (for example for OCR), or one of its sources reads from it. |
| Connections | For a gateway: connections routed through it. For a custom integration: connections to it. |
The same rule applies from the API:
deleting a connection that's in use returns 409 Conflict, with the list of what
uses it. GET …/{id}/usage returns the same list without deleting anything.