Developer quickstart

Guest Machines uses service principals for organization-owned automation. A service principal acts as the organization directly and is restricted by its scopes and optional resource allowlist.

Create an automation account

An organization owner or admin can open Settings → Apps and API Access → 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, pipelines, and chats are private by default, and a service principal can never reach a private resource regardless of its scopes. Before testing, share the specific agent, pipeline, or team the integration will use with the organization, or grant the automation account explicit access to it. See authentication for how visibility and scopes combine.

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"

Service-principal keys begin with gsmc_sk_ and are already bound to an organization. Human access tokens can select an active organization with X-Org-Id; service principals 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.