Skip to main content

Permissions and service accounts

Effective access​

Every request must satisfy all of these conditions:

  • The workspace's API beta is enabled.
  • The service account and its workspace membership are active.
  • The key is assigned, unrevoked, and unexpired.
  • Its workspace matches the URL, and any project is explicitly assigned.
  • The account's current role and the key's scopes both allow the operation.
  • The subscription and enabled business modules allow the operation.

An empty scope list grants no API access. Financial visibility scopes, such as expenses:view_amounts, are independent of read/write permissions. Approval and sending require their action scopes as well as write access where the reference specifies it.

A human manager cannot grant a service account permissions beyond their own authority. Permission changes take effect on the next request. Workspace keys cannot administer users, billing, security, service accounts, or other keys.

Service-account lifecycle​

Create and manage accounts in Workspace settings → Integrations → API keys. They are listed separately from people and never count toward paid seats. Use a descriptive name such as “Accounts export” or “Procurement connector”. Assign only the projects required by the integration.

Suspend temporarily disables every key for the account. Resume restores access subject to current permissions. Retire permanently disables the identity and revokes all keys while preserving audit history.

Removing the human creator does not remove the service account. Review service accounts and project access when employees leave.

Key rotation​

Create separate keys for separate integrations. Secrets are stored as hashes and are shown only once. The default expiry is 90 days; use shorter expiries for temporary work.

Regenerate immediately revokes the previous key and reveals its replacement once. For an overlap while updating an integration, issue a second key, switch the integration, then revoke the old key. Never put keys in URLs, browser code, logs, or source control.

Keys created before service accounts were introduced remain unusable until a manager explicitly assigns an active service account and reviews the scopes. Personal API keys are not accepted by v1.