Skip to main content
An API key is the credential your server, script, or CI job uses to call Kernel without an interactive login. Treat it like a password: keep it out of client-side code, store it in a secret manager, and rotate it when access changes. Kernel only returns the plaintext key once, when you create it. Save the key value immediately. After that, Kernel only shows the masked value.
For anything that isn’t a person at a keyboard, use workload identity federation 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 to choose.

Before you start

You need one existing Kernel credential to create another API key:
  • Set KERNEL_API_KEY before running the SDK examples.
API keys can be org or project scoped:
  • Omit project_id to create an org-scoped key that can access resources across your organization.
  • Set project_id to create a project-scoped key that can only access resources in that project.
  • When you authenticate with a project-scoped key, you can only create another project-scoped key for the same project.

Create an API key

Use the SDKs when your backend needs to provision keys for environments, customers, or automation jobs.

SDKs

Scope a key to specific resources

By default, an API key can do anything in its organization or project. Add a policy when you create a key to limit what it can do. Keys created without policy work exactly as before. Use scoped keys when you hand a credential to code you trust less than your backend, such as an AI agent or a short-lived job.

How policies work

A policy is a list of statements. Each statement allows one action on one resource, and the key is denied everything no statement allows.
  • A resource is either one object, projects/{project_id}/{kind}/{id}, or everything in a container, projects/{project_id}/* or organizations/{org_id}/*.
  • An action is {kind}:{verb}, such as browsers:use or vaults:read.
A statement can also carry a condition that narrows it to matching requests. A condition names a request attribute, a comparison operator, and that operator’s values. See Limit a key to your IP ranges. Some operations need more than one action. For example, creating a browser with a profile needs browsers:create and browsers:use on the project, plus profiles:use on that profile. See API key permissions for every action and what each operation requires.

Create a scoped key

This key can create and control browsers in one project, only with profile prof_7h2kq9x4m1 or no profile, and expires in one hour:

Expiry and revocation

  • Use expires_at for an exact expiry, such as minutes from now, instead of days_to_expire. A scoped key can’t outlive the key that creates it.
  • Expired and deleted keys can’t authenticate new API requests.
  • Deleting a key through the API or dashboard, or rotating it with expire_in_days: 0, also ends browser sessions associated with that key. Cleanup runs asynchronously and discards unsaved profile changes.
  • Grace-period expiry and natural expiry do not end existing browsers. Delete those browsers explicitly if you need to stop them.
  • If browser cleanup can’t be scheduled, deletion or immediate rotation fails without committing the key change.
  • Rotating a scoped key keeps its policy.
Automatic cleanup only covers browsers associated with the key. Some browsers created before this behavior was introduced may not have that association. Delete those browsers directly. Cleanup doesn’t undo profile changes you’ve already saved, delete browser pools, or stop app invocations or deployments.
Scoped keys can’t manage API keys, and they get 403 on endpoints that don’t support scoped access yet.

Limit a key to your IP ranges

Add a condition to a statement to restrict where requests can come from. The source_ip condition allows the statement only when the request’s client address is inside one of its CIDR networks:
Use this when a key is pinned to a fixed egress: if the key leaks into a log, a repository, or a third-party tool, requests from anywhere else get 403 before they touch your data. How conditions evaluate:
  • Each entry in values must be a CIDR network (203.0.113.0/24). A bare address without a mask, an entry with host bits set, and an IPv4 network written in IPv6 notation are rejected with 400 at creation—so a mistyped mask can’t silently grant a whole block.
  • Requests from outside every listed network get 403 with insufficient_scope, and the denial is recorded in your audit logs with the client IP, so you can widen the list from evidence.
  • A condition only narrows its own statement. If you want a key that only works from your network, add the same condition to every statement in its policy.
  • Kernel evaluates the address the trusted edge proxy reports, not a client-supplied header value, so a request can’t spoof its way in.

Add an IP allowlist to an existing key

You don’t need to rotate a key to add, change, or remove IP rules. Update the key with a policy, and the credential, name, project, and expiry stay the same—your consumers keep the same secret:
Updating policy fully replaces the key’s permissions, so send the complete policy, not just the statements you’re changing. The new policy takes effect within the authorization cache (~10 seconds) and applies only to new requests—already-open browser connections keep running. Attaching a policy to a key that doesn’t have one makes the key scoped: every action and resource the policy doesn’t list is denied. There’s no way to remove a policy from a key and go back to unrestricted—if you no longer need a scoped key, delete it.
A key used through a hosted MCP server is evaluated against the MCP server’s egress address, so an IP-restricted key is denied everywhere until MCP support ships. If you route keys through a hosted MCP server, leave source_ip conditions off those keys for now.

Deployment API keys

When you deploy an app, Kernel mints a deployment-scoped API key for that deployment and injects it into the deployment (and every invocation it runs) as the KERNEL_API_KEY environment variable. Because the SDKs read KERNEL_API_KEY from the environment by default, your app can call the Kernel API as itself without you managing a key. Key points about deployment keys:
  • One key per deployment. Each deploy (including a redeploy of the same app) mints a fresh deployment key. KERNEL_API_KEY is a reserved environment variable — a value you supply at deploy time is overridden by the injected key. To use your own long-lived key, pass it under a non-reserved name.
  • Lifecycle tied to the deployment. A deployment key stays valid while its deployment is active. When you redeploy, the new deployment supersedes the old one, and the old deployment’s key is released once it is no longer needed — that is, once the superseded deployment is stopped and no invocation is still running on it.
  • In-flight invocations are drained, not cut off. If an invocation is still running on a deployment that gets superseded, its key is kept valid until that invocation completes; the key is released right after. An idle redeploy (nothing in flight) releases the old key immediately. In the rare case where an invocation’s workflow terminates without releasing the key, a background sweep releases it after a grace period (~95 minutes). You do not need to manage any of this — it is automatic.
If you need a credential whose lifetime you control (for CI, a persistent backend, or a resource that should outlive any single deployment), create an org- or project-scoped key as described below and pass it explicitly to the client. This only affects the calls your app makes — the platform still injects the deployment key and uses it to run the invocation and report its result, so you’re choosing the credential for your own calls, not replacing the deployment key.

List and inspect API keys

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: In the dashboard, filter the list by Created by, Linked account, and Project, and switch between Active, Expired, and Deleted.

Rename, update permissions, or delete an API key

Rename a key when the owner or purpose changes. Update its policy to add, change, or remove IP rules and permissions without rotating the credential. Delete a key when the workload no longer needs access.
An API key cannot delete itself. Authenticate with a different key when deleting a key, so the request cannot revoke the credential that is authorizing it. Deleting a key also ends its associated browsers asynchronously and discards their unsaved profile changes.

Rotate a key

rotate issues a replacement key in a single call and keeps the old key working for a short grace period, so your workload can switch over without downtime. The new key copies the rotated key’s name, project scope, and policy, and—like create—Kernel returns the plaintext key only once. Two optional parameters control the timing:
  • days_to_expire sets the new key’s lifetime in days (1-3650). Omit it to give the new key the same lifetime the rotated key originally had, or to never expire if the old key never did.
  • expire_in_days sets how long the old key keeps working before it expires. Use 0 to revoke it immediately, or omit it for the default 7-day grace window. The old key stops authenticating automatically once the window passes—you don’t need to delete it.
After you rotate a key:
  1. Store the new plaintext key in your secret manager.
  2. Deploy or restart the workload that uses KERNEL_API_KEY.
  3. Verify the workload can call Kernel before the grace window ends.
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, an organization admin can link a key to a service account 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. It’s still a stored secret. Prefer federation wherever your workload has an identity provider, and move existing workloads when you can.

Troubleshooting