For AI agents: The documentation index is at https://docs.digitalocean.com/llms.txt. Markdown versions of pages use the same URL with index.html.md in place of the HTML page (for example, append index.html.md to the directory path instead of opening the HTML document).

An Action Gateway connection authorizes tools to access an account at a provider such as GitHub or Linear. It associates that authorization with an actor ID. A session uses its actor ID to select the connection for each provider it calls.

A tool provider defines the available tools. The connection determines which provider account those tools use. Several tools from one provider can use the same connection, subject to the account’s scopes and the session’s tool policy.

Connection Ownership

New connections belong to the DigitalOcean user who creates them, within the selected team. They are not automatically shared with every team member. Sessions created through the Control Panel or public API are also user-owned.

To use a connection, create the session and connection as the same DigitalOcean user, in the same team, with the same actor ID. Another team member using that actor ID does not gain access to your connection. A team owner can inspect connection records for administration, but that visibility does not authorize using or changing another user’s connection.

You can reuse a connection across sessions you own. For a given owner, actor, and provider, there is one connection. To use different accounts at the same provider, assign them different actor IDs and select the intended actor when creating a session.

Credentials and Connections

A provider credential and a connection serve different purposes. A credential supplies authentication material, such as an OAuth application’s client credentials or an API key. A connection associates the chosen credential and authorization with an actor for its owning user.

Depending on the provider, you can use DigitalOcean’s OAuth application, register your own OAuth client, or provide your own API key. An OAuth flow requires the user to sign in to the provider and approve the requested scopes. An API key uses the permissions already assigned to that key.

A provider credential can be explicitly made reusable by the team. This lets team members create their own connections using that credential; it does not turn an existing user-owned connection into a shared connection.

The gateway resolves credentials when the tool executes. The model receives tool inputs and results, not the stored provider secret. Never put provider secrets into session instructions, tool arguments intended for ordinary data, or an agent conversation.

Authorization Scope

You grant scopes in the third-party system. A full-access credential retains that access when used through Action Gateway. We do not reduce its provider-side scopes. Pair a least-privilege credential with an appropriately restricted tool policy.

Connection Lifecycle

You can authorize a provider before running a workload or complete authorization when a tool reports that a connection is required. Pre-authorize connections for unattended workloads that cannot stop for a provider sign-in.

A connection may need attention when authorization expires, is revoked, lacks a required scope, or needs provider-specific settings. Follow the returned connection guidance as the session’s owning user and authorize the same actor the session uses. Tool approval and provider authorization are separate decisions; approving a call does not grant OAuth scopes.

See Authorize Providers with Connections for the Control Panel and SDK procedures.

Existing Team-Scoped Connections

Older connections created without a user owner remain supported for compatibility. If no connection exists for the session owner, actor, and provider, the gateway can use a matching older team-scoped connection. If a user-owned connection exists but needs attention, the gateway does not switch to the older connection to bypass that problem.