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 represents the person or workload an agent acts for. Its actor ID is a label you choose, such as user-123, to link that person’s connected accounts to the sessions that should use them.

For example, your application might store a customer’s user record under user-123. Use that value as the actor ID when connecting their GitHub account and creating their session. The customer’s GitHub sign-in determines which GitHub account the tools access. The label user-123 does not sign in to GitHub or need to match their GitHub username.

For your own coding agent, you can use the default actor ID shown in the Control Panel. You do not need to build an application or create a user database first.

Default Actor ID

The Control Panel prefills Actor ID from the part of your DigitalOcean login email before @. For example, [email protected] produces sammy. It removes unsupported characters and limits the result to 64 characters.

You can see or change this value when you click Create session on the Sessions page or Add connection on the Connections page. For an existing session, open its details and copy its Actor ID when connecting accounts.

SDK and API callers must supply the actor ID explicitly to use these connections. They do not derive the Control Panel default from your DigitalOcean token. Copy the value from the Control Panel or choose your own, and use it for both the connection and session.

How an Actor Connects Accounts to Sessions

Suppose your issue-triage 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 user-123. When it calls a Linear tool, it uses that user’s Linear connection. Other sessions you create with user-123 can reuse both connections. To serve another user, connect that user’s accounts under a different ID, such as user-456.

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

For an application serving multiple users, reuse each person’s ID from your application’s user records or assign them a separate stable label. Actor IDs accept letters, numbers, periods, underscores, and hyphens. When choosing your own label, prefer an opaque user ID over an email address, name, or other personal information. Never include a secret.

Within a team, each owner and actor has one connection per provider. 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.

Reusing an Actor Across Sessions

Keep the actor ID when starting another task for the same user. The new session can reuse that user’s connected accounts while selecting different tools or permissions. For example, a read-only triage session and a session that requires approval to post comments can both use user-123.

Reauthorizing an existing connection does not require a new actor ID. Sessions using that actor can use the restored account access on later calls. To change which actor an existing session uses, create a replacement session. See Sessions.

Actor Identity and Authentication

Your application must authenticate its users and assign the correct actor ID. Do not let an untrusted request choose another user’s actor. Reusing an actor ID for unrelated users can give them access to the same connected accounts through your application.

The Actors tab lists actors and their sessions and connections. Use it to check that a session uses the intended accounts. A tool policy separately controls which operations the session can perform.

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.