Developer quickstart

Guest Machines supports user-owned keys and organization-owned automation accounts. For a script that should have your current workspace permissions, open Settings → API Access → API Keys. Any member can create their own key. Send the gsmc_uk_ key in the Bearer header shown below; no additional sharing or scopes are needed for resources you already have permission to use. Choose read-only access when the script only reads data.

The remaining setup below is for an automation account, an identity of its own that isn't tied to a person. It acts as the organization and is limited by its scopes and by the resources shared with it.

Create an automation account

An organization owner or admin can open Settings → API Access, choose Automation accounts, and create an account with the minimum scopes required by the integration.

The API key is shown once. Store it in a secret manager and never place it in browser code, source control, logs, or documentation examples.

Share the resources the integration needs

Agents and workflows are private by default, and an automation account can never reach a private resource regardless of its scopes. Chats belong to the member who started them, so an automation account never reaches one. Before testing, share the specific agent or workflow the integration will use with the organization. For an agent, you can instead set it to restricted visibility and have an organization owner or admin add the automation account to it. See authentication for how visibility and scopes combine.

To keep the account away from everything else the workspace shares, an owner or admin can also give it an allowlist: on the account's page, choose Edit Allowlist and pick the agents and workflows it may reach. While a list is set, the account can't open runs or upload files. See limit an automation account.

Authenticate the request

Send the key as a Bearer token. Listing agents needs the agents:read scope:

curl https://api.guestmachines.com/api/v1/agents \
  -H "Authorization: Bearer $GUEST_MACHINES_API_KEY"

Automation account keys begin with gsmc_sk_ and are already bound to an organization. Human access tokens can select an active organization with X-Org-Id; automation accounts do not need that header.

Handle the response

Treat 401 as missing or invalid authentication and 403 as an authenticated principal that lacks the required scope, role, visibility grant, or resource access.

A 200 carrying an empty list is the third case to plan for, and the easiest one to misread. List endpoints drop resources the caller cannot see instead of failing, so an empty result means one of three things: the workspace really is empty, the key lacks the read scope for that resource, or every matching resource is still private. Check visibility and scopes before concluding that authentication is at fault.

Before automating a write or execution call, read errors and retries and use an idempotency key wherever the endpoint supports one.

What you can depend on

The API reference is the supported contract: every endpoint in it is explicitly allowlisted, carries a compatibility promise, and states which credentials and scopes drive it.

Endpoints outside it belong to the web application. They are not documented, carry no promise, and can change in any deploy — observing the product call one is not permission to build on it.