Connect external services safely
Give an agent a bounded external capability without exposing reusable credentials or opening unnecessary network access.
Log in or sign up to make these docs interactive
Choose your team, project, or agent to turn guidance into links to the exact place in your workspace.
Connect the specific service and operation an agent needs. Treat credentials, network reach, tools, and permissions as separate boundaries that must all align.
Before you begin
Identify the destination, actions required, data involved, human owner, and a safe test operation. Decide whether the connection should be available to one agent, one project, or a broader team workflow.
Quick steps
- Open the selected agent's Tools and enable the narrowest capability that performs the required operation.
- Configure workspace network access for only the required destination; keep new or redirected hosts subject to approval.
- Open the agent's Secrets, add the destination-bound credential, and grant only the intended operation.
- Create a harmless test card that names the destination, input, expected result, and evidence to capture.
- Run the test, inspect the action record and remote result, then revoke or narrow any access the successful path did not use.
1. Choose the narrow capability
Prefer a purpose-built tool or bundle. If a custom HTTP tool is appropriate, define the approved destination and operation rather than a generic request client. Grant only the permissions needed to invoke and manage it.
Configure the capability from the selected agent's Tools page.
2. Configure network policy
Allow the required destination through the workspace's network preset or use the approval flow for a new destination. Keep outbound access disabled when the job does not need it. Review redirects and unexpected hosts rather than assuming they belong to the original service.
3. Add the secret for its destination
Enter the credential through the secrets flow. Secret values are write-only after entry and brokered to the intended request; the agent should not need to see or repeat them.
Use the selected agent's Secrets page so the value remains separate from instructions and tool definitions.
Use a service account with the narrowest practical scope. Do not place a secret in a card, prompt, file, wiki, or memory. If a value was exposed there, revoke it at the provider and replace it through the secrets flow.
4. Test a harmless operation
Delegate a card that performs a read or reversible action against noncritical data. Inspect the work stream for the destination, tool outcome, approval behavior, and any sensitive output. Confirm the result reaches the intended card or shared-content destination.
5. Expand only from observed need
If production work requires a broader operation, review that change on its own merits. Consider a separate tool or credential for consequential actions so read-only routines do not inherit write access.
Document the connection's owner, intended use, rotation process, and failure response in the relevant team or project knowledge.
What good looks like
The agent can complete the intended operation, cannot use the credential at an unrelated destination, and produces a visible record without exposing the secret. A teammate knows who owns the connection and how to revoke it.