key value immediately. After that, Kernel only shows the masked value.
Before you start
You need one existing Kernel credential to create another API key:- Set
KERNEL_API_KEYbefore running the SDK examples.
- Omit
project_idto create an org-scoped key that can access resources across your organization. - Set
project_idto 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 apolicy 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}/*ororganizations/{org_id}/*. - An action is
{kind}:{verb}, such asbrowsers:useorvaults:read.
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 profileprof_7h2kq9x4m1 or no profile, and expires in one hour:
Expiry and revocation
- Use
expires_atfor an exact expiry, such as minutes from now, instead ofdays_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.
403 on endpoints that don’t support scoped access yet.
Limit a key to your IP ranges
Add acondition 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:
403 before they touch your data.
How conditions evaluate:
- Each entry in
valuesmust 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 with400at creation—so a mistyped mask can’t silently grant a whole block. - Requests from outside every listed network get
403withinsufficient_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 apolicy, and the credential, name, project, and expiry stay the same—your consumers keep the same secret:
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 theKERNEL_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_KEYis 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.
List and inspect API keys
List keys to audit what exists. List and retrieve responses includemasked_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 itspolicy to add, change, or remove IP rules and permissions without rotating the credential. Delete a key when the workload no longer needs access.
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_expiresets 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_dayssets how long the old key keeps working before it expires. Use0to 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.
- Store the new plaintext key in your secret manager.
- Deploy or restart the workload that uses
KERNEL_API_KEY. - Verify the workload can call Kernel before the grace window ends.
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.