Service account and API key API
Create machine principals, assign scoped bindings, and issue one-time-revealed credentials.
Service accounts are organization principals for automation. API keys restrict those principals further; a scope cannot grant a permission absent from the account's role bindings.
Create a principal
/organizations/{organization_id}/service-accountsCreates a service-account principal without initial resource permissions.
Send name, owner_team_id, and an optional description. Returns 201 with the
account ID and revision. The account initially has no resource permissions.
An invalid owner team rejects creation.
/organizations/{organization_id}/service-accounts/{account_id}/bindingsCreates a scoped role binding for the service account.
Send
role_id and a scope object with type and ID. A project binding cannot refer
to a project in another organization. The caller cannot delegate authority it
is forbidden to grant.
Issue a key
/organizations/{organization_id}/service-accounts/{account_id}/keysIssues a scoped API key and reveals its plaintext once.
Requires access:write. Send name,
a nonempty scopes array, and expires_at. Organization policy can reject
non-expiring credentials or an excessive validity period.
To issue a bounded credential for droplet deployment, send:
{
"name": "payments-deployer",
"scopes": ["droplets:read", "droplets:write", "operations:read"],
"expires_at": "2025-12-15T00:00:00Z"
}The 201 response contains data.id, data.token, scopes, and expiry. Token
plaintext is revealed once. A later read returns metadata and a key prefix only.
If the create response is lost, revoke the uncertain key reference before issuing
a replacement rather than expecting to retrieve its plaintext.
Inspect access
/organizations/{organization_id}/service-accounts/{account_id}Returns the service-account identity, enabled state, owner, and configuration revision. Requires access:read.
/organizations/{organization_id}/service-accounts/{account_id}/bindingsReturns the account's visible role bindings and their scopes.
/organizations/{organization_id}/service-accounts/{account_id}/keysReturns key metadata, including creation, expiry, revocation, and observed last use when available. Last-use reporting can lag and is not a request audit.
Use the permission simulator for combined
role and key-scope evaluation. Granting droplets:write without operations:read
can permit creation while preventing the workflow from polling its result.
Revoke and disable
/organizations/{organization_id}/service-accounts/{account_id}/keys/{key_id}Revokes the selected API key.
Returns 204 and prevents new authorization through
that key.
/organizations/{organization_id}/service-accounts/{account_id}Updates the service account's enabled state.
Send enabled=false with the current ETag to disable the principal's new requests across its keys.
Accepted operations can continue after the account is disabled. For a compromised
account, use the credential-exposure procedure
to identify its active operations, check cancelable, and inspect completed changes.
Remove
/organizations/{organization_id}/service-accounts/{account_id}Deletes an unused service account after its bindings and keys are removed.
Delete role bindings and revoke keys before deleting the unused account. Resources created by it remain owned by their projects. Audit history retains the account and key reference, excluding token plaintext.
See API authentication, SCIM, and Roles and teams for distinct identity lifecycles.