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).

A connection authorizes Action Gateway to call a tool provider, such as GitHub or Linear, using a particular account. A tool that needs provider credentials cannot run until an appropriate connection exists for the session’s owner, actor, and provider.

Credentials are resolved when the tool executes, so they stay out of the model context. To create a session and connect your client, see Connect Action Gateway Tools. Authorize provider connections before or after creating the session, using the same DigitalOcean user, team, and actor ID.

If the provider you need is not listed, add its remote MCP server as a custom provider first. Custom providers support no authentication, an API key, or an OAuth connection.

Choose How a Connection Authenticates

Depending on the provider, a connection can authenticate with one of the following:

• A DigitalOcean-managed OAuth application.
• Your own OAuth application.
• A user API key.

You set the token’s permissions in the third-party product for each of these methods. Grant only the scopes the tool needs.

Create a Connection at Runtime

You do not have to set up a connection in advance. When a tool requires authorization and no valid connection exists, Action Gateway can start the authorization flow for that provider and create the connection once authorization completes.

This suits interactive work, where the user driving the agent can complete the provider’s sign-in when prompted.

Create a Connection Ahead of Time

For unattended workloads that cannot pause for a provider sign-in, create the connection before the application runs.

Create a Connection Using the Control Panel

1. In the Control Panel, go to Managed Agents, click Action Gateway, then open the Connections tab.
2. Click Add connection.
3. Select the provider, then choose an authentication method:
   • DigitalOcean’s OAuth app when the provider supports DigitalOcean-managed OAuth.
   • Your own OAuth client or Your own API key when you supply credentials. Register a new credential in the form, or select an available credential under Manage credentials.
4. Enter a stable Actor ID for the application user whose provider account you are connecting, such as user-123. Your sessions in this team use that ID to select the connection. To keep another connection to the same provider, use a different actor ID.
5. Review the Permissions (scopes) the provider requests, then click Connect.
6. If the provider uses OAuth, complete authorization in the provider window that opens. Wait until the connection shows as active.

The connection belongs to the DigitalOcean user who creates it, within the selected team. Other team members do not gain permission to use it by entering the same actor ID. See Connection Ownership for reusable credentials and legacy connections.

Create a Connection Using the SDK

Create a connection with PyDo or DoTs. These examples use DigitalOcean’s shared OAuth app for GitHub. If authorization is required, they display a URL and a verification code. Open the URL in your browser, compare the code shown there, and complete the provider sign-in. Then check that the connection is active.

Run the examples locally. Treat authorization URLs and verification codes as sensitive: do not paste them into an agent conversation, publish them, or write them to application logs. The example requests GitHub’s repo scope; request only the scopes your workload needs.

Replace <actor-id> with your application’s identifier for the user whose provider account you are connecting. Connection creation uses user_id in PyDo and userId in DoTs for this actor ID, not for a DigitalOcean user ID. Session creation uses actor_id in PyDo and actorId in DoTs for the same value. Use a token for the DigitalOcean user who owns the session, in the same team.

pip install pydo

import os

from pydo.action_gateway import ActionGatewayClient

ag_client = ActionGatewayClient(token=os.environ["DIGITALOCEAN_TOKEN"])

response = ag_client.connections.create(
    body={
        "provider": "github",
        "user_id": "<actor-id>",
        "scopes": ["repo"],
    },
)
connection_id = response["connection"]["id"]
authorization = response.get("authorization")
if authorization:
    print("Authorization URL:", authorization["connect_url"])
    print("Verification code:", authorization["verification_code"])
print("Connection status:", response["connection"]["status"])

response = ag_client.connections.get(id=connection_id)
print(response["connection"]["status"])

npm install @digitalocean/[email protected]

import { ActionGatewayClient } from "@digitalocean/dots/action_gateway";

const agClient = new ActionGatewayClient({
  apiKey: process.env.DIGITALOCEAN_TOKEN!,
});

const response = await agClient.connections.post({
  provider: "github",
  userId: "<actor-id>",
  scopes: ["repo"],
});
const connectionId = response?.connection?.id;
if (!connectionId) {
  throw new Error("Connection creation returned no connection ID.");
}
if (response?.authorization) {
  console.log("Authorization URL:", response.authorization.connectUrl);
  console.log("Verification code:", response.authorization.verificationCode);
}
console.log("Connection status:", response?.connection?.status);

const statusResponse = await agClient.connections.byId(connectionId).get();
console.log(statusResponse?.connection?.status);

The connection is ready when its status is active. If it is still pending, finish the browser authorization and repeat the status check. Use the existing connection ID for status checks rather than creating another connection.

Scope Connections to an Actor

An actor is a user-defined identity that associates an application user with provider connections. Pass the same ID you assigned to the connections as the session’s actor_id. Continue in the Python interpreter with the same authenticated client:

session = ag_client.session.create(
    actor_id="<actor-id>",
)

Later sessions owned by the same DigitalOcean user in the same team can reuse these connections by specifying the same actor ID. For example, use user-123-work and user-123-personal for one user’s work and personal GitHub accounts, then select the appropriate ID when creating each session. Calls through that session’s MCP URL use the selected actor’s connections.

Actor IDs do not authenticate your application’s users. Your application must authenticate each user and select the correct actor ID before creating or using a session. See Actors.

View Actors

You can view the actors for your agent in the Actors tab of Action Gateway in the Control Panel.