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 endpoints 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 endpoint. 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 choose an actor ID when creating an endpoint or adding a connection. For an existing endpoint, open its details and copy its Actor ID when connecting accounts. The automatically created default endpoint derives its initial actor from the email username and keeps it even if the email changes. See Default Endpoints.

When creating an endpoint through the API, supply the actor ID to use these connections. Copy the value from the Control Panel or choose your own, and use it for both the connection and endpoint.

How an Actor Connects Accounts to Endpoints

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 endpoint with actor ID user-123.

When the endpoint 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 endpoints 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 endpoint 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 endpoint.

Reusing an Actor Across Endpoints

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

Reauthorizing an existing connection does not require a new actor ID. Endpoints using that actor can use the restored account access on later calls. To use a different actor, create a separate endpoint. See Endpoints.

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 connections. Check that an endpoint uses the intended accounts. A tool policy separately controls which operations the endpoint 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.