Skip to main content
Service accounts are machine identities designed for automated processes and applications. Unlike human users, service accounts authenticate via API keys and are intended for programmatic access.

​
Workspace vs Project Level

Service accounts can be created at two levels:
  • Workspace level — Has access governed by workspace IAM policies. Suitable for cross-project automation.
  • Project level — Scoped to a single project, following the principle of least privilege. Suitable for isolated automation within one project.

​
Create a Service Account

  1. For workspace-level: go to IAM & Admin > Service Accounts and click Create.
  2. For project-level: go to the project, click Manage > Service Accounts, and click Create.
You can assign roles while creating the service account. After it’s created, click Copy Service Key on its row and store the key as a secret. The key can’t be viewed again later.
Service accounts cannot be part of user groups. Since service accounts are for automated processes with specific access needs, including them in groups could grant unintended permissions. This is considered an anti-pattern.

​
Manage Roles

Roles can only be set on the Service Accounts page while creating the account. To view or change the roles of an existing service account:
  • Workspace roles: go to IAM & Admin > Members. Service accounts are listed with a Service Account badge and their current roles. Click the edit icon on the row to change them.
  • Project roles: go to the project, click Manage > Members, and edit the service account there.

​
Reset the Service Key

If a key is lost or exposed, click Reset Service Key on the service account’s row. The new key is copied to your clipboard, and the old key can no longer be used to sign in.
Resetting the key doesn’t revoke access tokens already issued with the old key. They stay valid until they expire, which is 1 hour by default and follows the workspace’s Access token duration setting. To cut off access immediately, delete the service account. A deleted service account is rejected on its next request.

​
Delete and Restore

Deleting a service account deactivates it. It can no longer authenticate, but it is not removed permanently, and its email stays reserved. Creating a new service account with the same ID at the same level fails. To reuse a deleted service account:
  1. On the Service Accounts page, select Show inactive accounts.
  2. Click the restore icon on the service account.
  3. Click Reset Service Key to issue a new key.
Restoring also makes any unexpired access tokens issued before the deletion valid again, so restore only when you intend to use the account. A restored service account keeps the roles it had before it was deleted. Review them under Members after restoring. If you need an account with no previous roles, create one with a new ID.

​
Service Account vs Workload Identity

If your automation runs in a CI/CD platform that supports OIDC, prefer Workload Identity for better security.