Service Accounts

Service accounts are machine identities that receive scoped credentials. They are useful for CI/CD pipelines, background workers, and integrations that should not use a personal user token. Each service account has a client_id and client_secret. The secret is returned only on creation and rotation; at all other times only its SHA-256 hash is stored.

Base URL

Endpoints

Scopes

Scopes are passed as a comma-separated string on creation or update and returned as an array. Typical scopes include:
  • gateway:read
  • gateway:write
  • admin

Create a service account

Request body

Response

Save the client_secret immediately. It cannot be retrieved later.

List service accounts

Response

Update a service account

Response

Rotate a client secret

Response

Rotation invalidates the previous secret immediately.

Authenticate with a service account

Use the client_id and client_secret as a Bearer token or exchange them for an access token according to your organization’s auth flow. Pass the resulting token in the Authorization header:

Error codes

  • Access tokens — organization access tokens for CLI surfaces
  • Workspaces — scope service accounts to workspaces
  • RBAC — fine-grained roles and groups