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 actor is a user-defined identity for the person or workload whose connected accounts a session uses. Its actor ID is a string you choose and assign to both provider connections and sessions. This associates a user’s accounts, such as GitHub or Linear, with the Action Gateway sessions that should use them.

For example, an application can use its own user identifier, user-123, as an actor ID. That value is an example application ID, not a DigitalOcean account ID, provider username, or session ID.

How an Actor Connects Accounts to Sessions

Suppose your application lets a user work with their GitHub repositories and Linear issues:

1. Authorize a GitHub connection with actor ID user-123.
2. Authorize a Linear connection with the same actor ID.
3. Create an Action Gateway session with actor ID user-123.

When the session calls a GitHub tool, Action Gateway uses the GitHub connection for that actor. When it calls a Linear tool, it uses the Linear connection. Other sessions you create with user-123 can reuse those connections. A session with user-456 uses a different set of connections.

Create the session and connections as the same DigitalOcean user, in the same team. Matching an actor ID does not grant access to another DigitalOcean user’s connections. See Connection Ownership.

Choosing an Actor ID

Use a stable identifier from your application for the user or workload. Actor IDs accept letters, numbers, periods, underscores, and hyphens. Avoid email addresses, names, secrets, or other personal information.

Reuse an ID when sessions should use the same connected accounts. Do not generate a new actor ID for every session unless you intend to keep its connections separate. Within sessions you own, assigning the same actor ID to unrelated application users can cause them to use the same provider authorization.

For a given owner and actor, each provider has one connection. To connect multiple accounts for the same provider, use separate actor IDs. For example, user-123-work and user-123-personal can select different GitHub accounts for the same application user. Choose the appropriate ID when creating the session.

Actor Identity and Authentication

An actor ID selects connections; it is not a credential or a login. These identities have different roles:

Your application must authenticate its users and assign the correct actor ID. Do not let an untrusted request choose another application user’s actor. A tool policy separately determines which calls the session can make; changing the actor does not grant permission to additional tools.

The Actors tab lists actors and their sessions and connections. Use it to check that a session is associated with the intended accounts. See Authorize Providers to create a connection and Manage Sessions to select its actor.

Actor Rate Limits

Actors also let you set lower request-rate limits for an application user or workload. Select an actor in the Actors tab to view its Limits, including the effective limits and any actor-specific values configured for Exa web search, Exa web fetch, DigitalOcean tools, and external provider tools. See View and Lower Actor Limits to change a limit or restore the team default. Actor-specific limits cannot increase the team’s limits.