> ## Documentation Index
> Fetch the complete documentation index at: https://www.kernel.sh/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Service Accounts

> Named, non-human identities for your workloads, and the service account API keys to use when a workload can't federate

A **service account** (`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](https://www.kernel.sh/docs/info/workload-identity/overview.md#federation-rules)**, which issues short-lived tokens. Use this wherever your workload has an identity provider.
* **Through a [service account API key](#service-account-api-keys)**, for workloads that can't federate.

Either way, the service account outlives the people who set it up. A personal API key acts as the person who created it. A service account credential acts as the service account, so it keeps its meaning when that person changes teams or leaves.

## 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.

1. In the [dashboard](https://dashboard.onkernel.com), open **Keys** in the sidebar and select **Service accounts**.
2. Click **Create service account**.
3. Enter a **Name**, such as `browser-ci`, and an optional **Description**.
4. Click **Create service account**.

You can also create one inline in the **Target** step of **Connect workload**, or from the **Linked account** select when you create an API key.

Open a service account to see its ID, when it was created and last used, the **API keys** linked to it, and the **Federation rules** that target it.

## 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](https://www.kernel.sh/docs/info/api-key-permissions.md).

* **Browsers** it creates are recorded as created by the service account. Creating a browser needs `browsers:create` and `browsers: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:

| Closed | Why |
| - | - |
| Acquiring a browser from a [pool](https://www.kernel.sh/docs/browsers/pools.md) | A pool lease records a user, not a service account. |
| [App](https://www.kernel.sh/docs/apps/deploy.md) deployments and invocations, including attaching a browser to an invocation and listing or deleting an invocation's browsers | Deployments and invocations identify their caller as a user. |
| Managing API keys | A service account's policy can't include API key permissions. |

If a workload needs one of these, use a personal [API key](https://www.kernel.sh/docs/info/api-keys.md) 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

> [!TIP]
>
> A service account API key is still a stored secret that works from anywhere until it expires or you delete it. If your workload runs on GitHub Actions, AWS, Google Cloud, Azure, or Kubernetes, use a [federation rule](https://www.kernel.sh/docs/info/workload-identity/overview.md) instead.

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.

1. Open **Keys** in the sidebar and select **API keys**.
2. Click **Create API Key**, then **Continue with an API key**.
3. Under **Linked account**, select the service account, or select **Create a service account**.
4. Choose a **Project**.
5. Set an **Expiration**. Pick the shortest one your workload can live with.
6. Under **Permissions**, grant the actions the workload needs.
7. Create the key and copy it. KERNEL shows the plaintext key once.

You can start from the service account instead: open it and click **Create key** in the **API keys** section. The account is preselected.

### 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.

To find these keys, filter the **API keys** list by **Linked account**, or list them through the API with `principal_type=service_account` or `service_account_id`. See [List and inspect API keys](https://www.kernel.sh/docs/info/api-keys.md#list-and-inspect-api-keys).

When your workload gains an identity provider, [move it to federation](https://www.kernel.sh/docs/info/workload-identity/migrate-from-api-keys.md) and delete the key.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.