Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 22 additions & 0 deletions docs.json
Original file line number Diff line number Diff line change
Expand Up @@ -286,6 +286,28 @@
"pages": [
"introduction/manage",
"info/projects",
"info/authentication",
{
"group": "Workload Identity Federation",
"pages": [
"info/workload-identity/overview",
"info/workload-identity/service-accounts",
{
"group": "Providers",
"pages": [
"info/workload-identity/github-actions",
"info/workload-identity/aws",
"info/workload-identity/google-cloud",
"info/workload-identity/microsoft-entra",
"info/workload-identity/kubernetes",
"info/workload-identity/custom-oidc"
]
},
"info/workload-identity/migrate-from-api-keys",
"info/workload-identity/reference",
"info/workload-identity/troubleshooting"
]
},
"info/api-keys",
"info/api-key-permissions",
"info/audit-logs",
Expand Down
30 changes: 22 additions & 8 deletions info/api-key-permissions.mdx
Original file line number Diff line number Diff line change
@@ -1,9 +1,23 @@
---
title: "API Key Permissions"
description: "Actions and resources you can grant in a scoped API key policy"
title: "Scoping Permissions"
description: "Actions and resources you can grant in a policy for an API key, a federation rule, or a service account API key"
---

This page lists everything you can grant in a scoped API key's `policy`. To create a scoped key, see [Scope a key to specific resources](/info/api-keys#scope-a-key-to-specific-resources).
A **policy** limits what a credential can do. It's a list of allow statements, each pairing one action with one resource, and everything it doesn't list is denied. This page lists everything you can grant in a policy.

## Where policies apply

Three kinds of credential carry a policy, and all three use the same format:

| Credential | Policy | Boundary |
| --- | --- | --- |
| [Scoped API key](/info/api-keys#scope-a-key-to-specific-resources) | Optional. A key without a policy is unrestricted inside its organization or project. | The key's organization, or its project for a project-scoped key. |
| [Federation rule](/info/workload-identity/overview#federation-rules) | Required. | The rule's one project. |
| [Service account API key](/info/workload-identity/service-accounts#service-account-api-keys) | Required. | The key's one project. |

Every resource in a policy must be inside its credential's boundary. A few operations stay closed to federation rules and service account API keys whatever their policy grants. See [what a service account can't do](/info/workload-identity/service-accounts#what-a-service-account-cant-do).

For a CI job, cloud service, or Kubernetes pod, put the policy on a federation rule instead of a stored key. See [API authentication](/info/authentication) to choose.

## Resources

Expand All @@ -13,7 +27,7 @@ This page lists everything you can grant in a scoped API key's `policy`. To crea
| `projects/{project_id}/*` | Everything in the project. |
| `projects/{project_id}/{kind}/{id}` | One object. `kind` is `browsers`, `profiles`, `vaults`, or `proxies`. |

Resources must be inside the new key's organization, or its project for a project-scoped key. Kernel checks that every object ID exists when you create the key.
Resources must be inside the credential's boundary: the organization, or the one project for a project-scoped key, a federation rule, or a service account API key. Kernel checks that every object ID exists when you create or update the key or rule.

## Conditions

Expand All @@ -31,7 +45,7 @@ A statement can carry one condition that narrows it to matching requests:

How conditions evaluate:

- A condition only narrows its own statement. To restrict a whole key, add the same condition to every statement.
- A condition only narrows its own statement. To restrict a whole credential, add the same condition to every statement.
- Requests from outside every listed network get `403` with `insufficient_scope`, recorded in your [audit logs](/info/audit-logs) with the client IP.
- A scoped key can't delegate a wider condition than it holds: a delegated key can narrow its parent's IP rules, never loosen them.
- You can add or change IP rules on an existing key without rotating its credential. See [Limit a key to your IP ranges](/info/api-keys#limit-a-key-to-your-ip-ranges).
Expand Down Expand Up @@ -88,11 +102,11 @@ How conditions evaluate:
| Add or remove a card in a Kernel wallet (`add_payment_method`, `remove_payment_method`) | `vaults:use` and `vaults:write` on the vault. Without `vaults:write`, the wallet doesn't list either operation in `available_operations`, and invoking one returns `403` with `insufficient_scope`. Other wallet and purchase operations need only `vaults:use`. |
| Run a proxy health check | `proxies:use` and `proxies:read`. |

List endpoints return only the objects the key can access, so a key without a matching grant gets an empty list.
List endpoints return only the objects the credential can access, so a credential without a matching grant gets an empty list.

## Not available to scoped keys
## Not available to credentials with a policy

Scoped keys get `403` with `insufficient_scope` on:
A credential with a policy gets `403` with `insufficient_scope` on:

- API key management, including creating, listing, rotating, and deleting keys.
- Browser pools.
Expand Down
24 changes: 24 additions & 0 deletions info/api-keys.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,10 @@ An API key is the credential your server, script, or CI job uses to call Kernel

Kernel only returns the plaintext key once, when you create it. Save the `key` value immediately. After that, Kernel only shows the masked value.

<Tip>
**For anything that isn't a person at a keyboard, use [workload identity federation](/info/workload-identity/overview) instead of an API key.** An API key is a stored secret that works until someone revokes it. With federation, a CI job, cloud service, or Kubernetes pod exchanges a token from its own identity provider for a short-lived KERNEL access token, and there's no secret to store. API keys remain the right tool for local development and for environments with no identity provider. See [API authentication](/info/authentication) to choose.
</Tip>

## Before you start

You need one existing Kernel credential to create another API key:
Expand Down Expand Up @@ -261,6 +265,18 @@ If you need a credential whose lifetime you control (for CI, a persistent backen

List keys to audit what exists. List and retrieve responses include `masked_key`, `project_id`, `project_name`, `created_by`, expiry metadata, and `policy` for scoped keys, but they don't include the plaintext key.

The list returns `active` keys by default: keys that are neither deleted nor expired. Pass `status` to see the others, and combine these filters to narrow the list:

| Query parameter | Returns |
| --- | --- |
| `status` | `active` (the default), `expired`, `deleted`, or `all`. Expired keys aren't part of `active`. |
| `principal_type` | `user` for keys that act as a person, or `service_account` for keys that act as a [service account](/info/workload-identity/service-accounts). |
| `service_account_id` | Keys that belong to one service account. |
| `created_by` | Keys created by one user ID. |
| `project_id` | Keys scoped to one project. Use `org` for keys that aren't scoped to a project. |

In the dashboard, filter the list by **Created by**, **Linked account**, and **Project**, and switch between **Active**, **Expired**, and **Deleted**.

<CodeGroup>
```typescript TypeScript
for await (const apiKey of kernel.apiKeys.list({ limit: 20 })) {
Expand Down Expand Up @@ -459,6 +475,14 @@ After you rotate a key:

To cut over immediately instead of using a grace window, pass `expire_in_days: 0`. The old key stops working, its associated browsers are ended asynchronously, and unsaved profile changes in those browsers are discarded. With a grace period, existing browsers keep running after the old key expires.

## Service account API keys

A key you create for yourself acts as you. For a workload that can't use [workload identity federation](/info/workload-identity/overview), an organization admin can link a key to a [service account](/info/workload-identity/service-accounts) instead, so the key belongs to the organization and keeps working when its creator leaves.

A service account API key always has one project and an explicit policy, and it can't hold API key permissions. Create one from the dashboard: click **Create API Key**, choose **Continue with an API key**, and pick the service account under **Linked account**. See [Service account API keys](/info/workload-identity/service-accounts#service-account-api-keys).

It's still a stored secret. Prefer federation wherever your workload has an identity provider, and [move existing workloads](/info/workload-identity/migrate-from-api-keys) when you can.

## Troubleshooting

| Error | What it means | What to do |
Expand Down
65 changes: 65 additions & 0 deletions info/authentication.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,65 @@
---
title: "API Authentication"
description: "Choose how your code authenticates to KERNEL: workload identity federation for workloads, API keys for local development"
---

Every request to the KERNEL API carries a credential in the `Authorization: Bearer` header.

**Use [workload identity federation](/info/workload-identity/overview) for anything that isn't a person at a keyboard.** A CI job, a cloud service, or a Kubernetes pod already has an identity from its platform. Federation exchanges that identity for a short-lived KERNEL access token, so there's no long-lived secret to store, rotate, or leak. Each access token lasts five minutes by default, and the SDK requests a new one before it expires, so a workload of any length stays authenticated.

## Why federation instead of an API key

By default, a static API key works from anywhere, for anyone who holds it, until someone revokes it. A federated credential doesn't have that failure mode.

| | Static API key | Workload identity federation |
| --- | --- | --- |
| **What you store** | A secret, in a CI variable, a secret manager, or an environment file. | Nothing. The rule ID your workload sends isn't a secret. |
| **Lifetime** | Until it expires or you delete it. Expiry is optional and can be up to 3,650 days. | 300 seconds by default, 600 at most. The SDK exchanges a fresh token before it expires. |
| **If it leaks** | It works until you revoke it, from any machine, or only from the [IP ranges](/info/api-keys#limit-a-key-to-your-ip-ranges) you limited it to if you set them. | The token stops working within minutes, and nobody can get a new one without your workload's own identity. |
| **Who can use it** | Anyone who has the string. | Only the workload your federation rule names, such as one repository, workflow, and branch. |
| **Scope** | Your whole organization or one project. A policy is optional. | Always one project and an explicit policy. |
| **Rotation** | You rotate it and redeploy every consumer. | Nothing to rotate. |
| **Turning it off** | Delete the key. | Disable the rule, issuer, or service account. Issued tokens stop working within about 10 seconds. |
| **Attribution** | The person who created the key, or a service account. | A named service account, with a record of each token it was issued. |

## Which one to use

| Your code runs in | Use |
| --- | --- |
| A GitHub Actions workflow | [Federation with GitHub Actions](/info/workload-identity/github-actions) |
| AWS (ECS, Lambda, EC2) | [Federation with AWS](/info/workload-identity/aws) |
| Google Cloud (GKE, Cloud Run, Compute Engine) | [Federation with Google Cloud](/info/workload-identity/google-cloud) |
| Azure, with a managed identity or an app registration | [Federation with Microsoft Entra](/info/workload-identity/microsoft-entra) |
| A Kubernetes cluster | [Federation with Kubernetes](/info/workload-identity/kubernetes) |
| Any other platform that issues OIDC tokens | [Federation with a custom OIDC issuer](/info/workload-identity/custom-oidc) |
| A server or tool with no identity provider | A [service account API key](/info/workload-identity/service-accounts#service-account-api-keys), limited to one project and an explicit policy |
| Your laptop, while you develop | `kernel login` for the [CLI](/reference/cli/auth), or a personal [API key](/info/api-keys) with a short expiry for the SDKs |
| A KERNEL app deployment | The [deployment key](/info/api-keys#deployment-api-keys) KERNEL injects for you |
| An MCP client such as Claude or Cursor | [OAuth](/reference/mcp-server/authentication) |

## When an API key is still the right tool

For some jobs an API key is still a reasonable choice:

- **Local development.** Your laptop has no workload identity. Sign in with `kernel login`, or create a personal key with a short expiry.
- **Environments with no identity provider.** A VM at a host that issues no OIDC tokens, or a third-party tool that only accepts a key, can't federate. Give it a [service account API key](/info/workload-identity/service-accounts#service-account-api-keys) so the key belongs to your organization, not to the person who created it.
- **Access across projects.** A federation rule covers one project. A task that needs every project in your organization at once needs an organization-scoped key.
- **Features closed to service accounts.** Acquiring a browser from a [pool](/browsers/pools), deploying or invoking [apps](/apps/deploy), and managing API keys aren't available to federated credentials. See [what a service account can't do](/info/workload-identity/service-accounts#what-a-service-account-cant-do).

When you do use an API key, limit what a leak can reach: scope it to one project, give it a [policy](/info/api-keys#scope-a-key-to-specific-resources) and a short expiry, and [limit it to your IP ranges](/info/api-keys#limit-a-key-to-your-ip-ranges) if it's used from a fixed network.

If you already run workloads on API keys, [move them to federation](/info/workload-identity/migrate-from-api-keys) one at a time. Both credentials work side by side while you switch.

## Next steps

<Columns className="responsive-columns" cols={3}>
<Card title="Workload identity federation" icon="fingerprint" href="/info/workload-identity/overview">
How the exchange works, and how to connect your first workload.
</Card>
<Card title="Move off API keys" icon="right-left" href="/info/workload-identity/migrate-from-api-keys">
Switch an existing workload without downtime.
</Card>
<Card title="API keys" icon="key" href="/info/api-keys">
Create, scope, rotate, and delete keys.
</Card>
</Columns>
4 changes: 4 additions & 0 deletions info/projects.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -112,6 +112,10 @@ API keys can be **org-wide** or **project-scoped**.

OAuth tokens (used by the Kernel CLI and MCP server) are **always org-wide**. You cannot bind an OAuth session to a single project. To scope OAuth-authenticated requests, send the `X-Kernel-Project-Id` header with each request — or use the CLI's `--project` flag (see below).

### Workload identity federation

A [federation rule](/info/workload-identity/overview#federation-rules) names exactly one project, and the tokens it issues work only in that project. So does a [service account API key](/info/workload-identity/service-accounts#service-account-api-keys). To give a workload access to two projects, such as `staging` and `production`, create one rule for each.

## Using projects from the CLI

The Kernel [CLI](/reference/cli/projects) has first-class project support:
Expand Down
Loading
Loading