API authentication

Create scoped service-account credentials and rotate or revoke machine access.

API credentials authenticate service accounts. Effective access is the intersection of the account's role bindings, the credential's scopes, and organization policy.

Create a service accountCopy link

Open Organization settings → Service accounts → Create. Assign an owner team, describe its deployment purpose, and bind it to the required projects or regions. A service account has no permissions until a role binding grants them.

Select Create API key, choose scopes and expiry, and copy the displayed token. The plaintext appears once. Store it in the automation system's secret store; do not commit it to a repository or include it in user data.

ScopesCopy link

Choose scopes by the resource surface. droplets:read and droplets:write cover guest configuration, templates, and placement groups. images:read and images:write cover regional boot artifacts. volumes:read and volumes:write cover block devices, attachments, and snapshots. Independent backup policies and runs use backups:read and backups:write.

networks:read and networks:write cover networks, subnets, interfaces, routes, firewalls, public addresses, load balancers, and DNS. Organization host and storage-pool administration use fleet:read and fleet:write.

Observation reads use metrics:read, logs:read, and alerts:read. Alert-rule changes require alerts:write. Maintenance requests use maintenance:write; protected approval additionally requires maintenance:approve.

Access administration uses access:read and access:write. Project administration uses projects:read and projects:write. Secrets use secrets:read and secrets:write; read scope never returns stored plaintext. Connector administration uses connectors:read and connectors:write.

Guest console creation requires droplets:console; rescue actions require droplets:recovery. Both also require their target-specific role permissions. Blueprint planning and state reads use blueprints:read; changes use blueprints:write in addition to child-resource scopes required by an apply.

Temporary grant approval requires access:approve. Governance reads and changes use governance:read and governance:write. Backup holds require backups:hold; releasing them requires the separate backups:hold_release scope.

Audit querying requires audit:read; exports require audit:export as well as access to the selected audit scope. Webhook reads use webhooks:read; administration uses webhooks:write. Operation polling requires operations:read; cancellation requires operations:cancel and an operation with cancelable=true.

Object-storage administration uses objects:read and objects:write. S3 data access uses separately issued object credentials and bucket policy. Autoscaling groups use autoscaling:read and autoscaling:write plus the child resource permissions required by their actions.

Brokered access uses sessions:connect. Recording reads and exports require sessions:recordings_read and sessions:recordings_export respectively, plus the target's recording policy. Those scopes do not grant direct guest login.

Write scopes do not implicitly grant all read scopes. Include the read and operation scopes needed by a workflow. A key with fleet:write still cannot administer a region excluded by the account's role bindings.

Send a requestCopy link

Set INFRA_API_URL to the intended /api/v1 base URL and INFRA_API_TOKEN through the process environment or secret injector. The following example reads droplets in a project for which the account has droplets:read.

To list droplets in the selected project, send an authenticated request:

curl --fail-with-body \
  --header "Authorization: Bearer ${INFRA_API_TOKEN}" \
  --header 'Accept: application/json' \
  "${INFRA_API_URL}/organizations/org_main/projects/prj_payments/droplets"

Protect the execution environment from users who should not read the credential. Do not enable command tracing when commands contain bearer headers.

Expiry and rotationCopy link

Expiry is required unless organization policy explicitly allows a non-expiring key. An expired key returns 401 for new requests. Expiry does not stop operations already accepted under that key.

To rotate a key:

1. Open Organization settings → Service accounts, select the account, and choose Create API key with the required scopes and expiry.
2. Replace the credential in the automation system's secret store.
3. Run the automation's read and write checks in its permitted test scope. Confirm that both requests succeed with the replacement key.
4. Select the old key in the same account and choose Revoke. Record the owner and completion time of the rotation.

Revocation and removalCopy link

To stop requests from one key, open Organization settings → Service accounts, select its account and key, and choose Revoke. Once revocation is applied, new requests with that key fail authentication. To stop requests from all of an account's keys, disable the service account.

To reduce an account's permissions while keeping its keys valid, remove the unwanted role binding. Other independent bindings can still grant access.

Respond to a credential exposureCopy link

Revoking a key does not cancel work already accepted under it. After revocation:

1. Open the audit log, find requests using the exposed key ID, and record their operation and resource IDs.
2. Open Operations → Queue and select each active operation from those requests.
3. If cancelable is true, select Cancel and wait for Succeeded, Failed, or Canceled. If it is false, follow the operation's journal until its outcome is established; do not start a competing action against the same resource.
4. Open each affected resource from the operation result. Compare its observed state with the completed steps. For unwanted running droplets, use Start and stop. For deleted or corrupted application data, follow Restore an application using a retained recovery point.

Cancellation stops uncommitted work. It does not reverse a completed migration, expansion, or deletion.

AuditCopy link

Key creation, rotation, revocation, and service-account changes appear in the audit log. Resource mutations identify the service account and key reference without recording the bearer token. Use a separate account per automation purpose so access and incident review remain scoped.