svc_...) is a named identity your organization owns, for software instead of people. Workloads act as a service account in two ways:
- Through a federation rule, which issues short-lived tokens. Use this wherever your workload has an identity provider.
- Through a service account API key, for workloads that can’t federate.
What a service account is
A service account has a name and a description, and nothing else. It holds no permissions. Each rule or key that uses it carries its own project, policy, and expiry, so one service account can back a rule for staging and a rule for production with different permissions. Names use letters, numbers, and hyphens, up to 128 characters, and start with a letter or number.Create a service account
Only an organization admin can create, edit, or archive a service account. Any member can view them.- In the dashboard, open Keys in the sidebar and select Service accounts.
- Click Create service account.
- Enter a Name, such as
browser-ci, and an optional Description. - Click Create service account.
What a service account can do
A service account credential can do what its rule’s or key’s policy grants, inside that rule’s or key’s one project. The policy uses the same actions and resources as a scoped API key. See Scoping permissions.- Browsers it creates are recorded as created by the service account. Creating a browser needs
browsers:createandbrowsers:use, plus permission on any profile, vault, or proxy the browser attaches. - Other resources, such as profiles and proxies, can be created when the policy grants it. They record no creator.
What a service account can’t do
Three things are closed to service accounts, whatever the policy says:
If a workload needs one of these, use a personal API key for that part.
Last used
A service account’s Last used time updates when one of its rules issues a token or one of its API keys authenticates. It’s recorded at most once every 15 minutes, so it can trail real use by a little more than that. Use it to find service accounts that nothing uses anymore.Archive a service account
Archiving stops everything that acts as the service account. New token exchanges are refused, and tokens already issued stop working within about 10 seconds. Archiving keeps the account’s history and can’t be undone. Creating a service account with the same name later gives you a new ID, and nothing that pointed at the old one moves to it. Archiving doesn’t delete browsers the service account created. Delete those yourself. To archive, open the row’s menu on the Service accounts page and select Archive.Service account API keys
Some workloads can’t federate: a VM at a host with no identity provider, or a third-party tool that only accepts a key. For those, link an API key to a service account. The key acts as the service account, not as you, and it keeps working after you leave the organization. A service account API key always has:- One project. It can’t be organization-wide.
- An explicit policy. There’s no unrestricted service account key. The policy can’t grant API key permissions.
Create a service account API key
Only an organization admin can create one, from the dashboard. Creating one isn’t currently possible with an API key or a federated token.- Open Keys in the sidebar and select API keys.
- Click Create API Key, then Continue with an API key.
- Under Linked account, select the service account, or select Create a service account.
- Choose a Project.
- Set an Expiration. Pick the shortest one your workload can live with.
- Under Permissions, grant the actions the workload needs.
- Create the key and copy it. KERNEL shows the plaintext key once.
Manage a service account API key
An admin can rename, rotate, or delete a service account API key, and can replace its permissions in place without issuing a new secret.- Rotating keeps the service account, project, and policy.
- Deleting one key doesn’t affect the service account or its federation rules.
- The creator is for audit only. The key shows who created it, but it doesn’t act as that person and doesn’t stop working when they leave.
principal_type=service_account or service_account_id. See List and inspect API keys.
When your workload gains an identity provider, move it to federation and delete the key.