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

# API Authentication

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

## 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](https://www.kernel.sh/docs/info/workload-identity/service-accounts.md#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](https://www.kernel.sh/docs/browsers/pools.md), deploying or invoking [apps](https://www.kernel.sh/docs/apps/deploy.md), and managing API keys aren't available to federated credentials. See [what a service account can't do](https://www.kernel.sh/docs/info/workload-identity/service-accounts.md#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](https://www.kernel.sh/docs/info/api-keys.md#scope-a-key-to-specific-resources) and a short expiry, and [limit it to your IP ranges](https://www.kernel.sh/docs/info/api-keys.md#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](https://www.kernel.sh/docs/info/workload-identity/migrate-from-api-keys.md) one at a time. Both credentials work side by side while you switch.

## Next steps

> [card] [Workload identity federation](https://www.kernel.sh/docs/info/workload-identity/overview.md)
>
> How the exchange works, and how to connect your first workload.

> [card] [Move off API keys](https://www.kernel.sh/docs/info/workload-identity/migrate-from-api-keys.md)
>
> Switch an existing workload without downtime.

> [card] [API keys](https://www.kernel.sh/docs/info/api-keys.md)
>
> Create, scope, rotate, and delete keys.


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