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

# Scoping Permissions

> Actions and resources you can grant in a policy for an API key, a federation rule, or a service account API key

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](https://www.kernel.sh/docs/info/api-keys.md#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](https://www.kernel.sh/docs/info/workload-identity/overview.md#federation-rules) | Required. | The rule's one project. |
| [Service account API key](https://www.kernel.sh/docs/info/workload-identity/service-accounts.md#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](https://www.kernel.sh/docs/info/workload-identity/service-accounts.md#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](https://www.kernel.sh/docs/info/authentication.md) to choose.

## Resources

| Resource | Matches |
| - | - |
| `organizations/{org_id}/*` | Everything in the organization. |
| `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 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

A statement can carry one condition that narrows it to matching requests:

```json theme={null}
"condition": { "key": "source_ip", "operator": "in", "values": ["203.0.113.0/24"] }
```

| Field | Value |
| - | - |
| `key` | `source_ip` — the request's client address. |
| `operator` | `in` — the statement matches when the address is inside one of `values`. |
| `values` | 1-16 CIDR networks, such as `203.0.113.0/24` or `2001:db8::/32`. A bare address without a mask and an entry with host bits set are rejected, as is an IPv4 network written in IPv6 notation. |

How conditions evaluate:

* 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](https://www.kernel.sh/docs/info/audit-logs.md) 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](https://www.kernel.sh/docs/info/api-keys.md#limit-a-key-to-your-ip-ranges).

## Actions

### Browsers

| Action | Allows |
| - | - |
| `browsers:create` | Create browsers. Grant it on a project or organization. |
| `browsers:use` | List, inspect, connect to, and control browsers. |
| `browsers:write` | Update browser configuration. |
| `browsers:delete` | Delete browsers. |

### Profiles

| Action | Allows |
| - | - |
| `profiles:create` | Create profiles. Grant it on a project or organization. |
| `profiles:read` | List profiles and view their metadata. |
| `profiles:use` | Attach profiles to browsers and download them. |
| `profiles:write` | Rename profiles and save browser state into them. |
| `profiles:delete` | Delete profiles. |

### Vaults

| Action | Allows |
| - | - |
| `vaults:create` | Create vaults. Grant it on a project or organization. |
| `vaults:read` | List vaults and view vault and item metadata. |
| `vaults:use` | Link vaults to browsers, fill credentials, and run vault item operations. |
| `vaults:write` | Create, update, and delete vault items. |
| `vaults:delete` | Delete vaults and their items. |

### Proxies

| Action | Allows |
| - | - |
| `proxies:create` | Create proxies. Grant it on a project or organization. |
| `proxies:read` | List proxies and view their configuration, without credentials. |
| `proxies:use` | Select saved proxies for browsers and run health checks. |
| `proxies:write` | Rename proxies. |
| `proxies:delete` | Delete proxies. |

## Operations that need more than one action

| Operation | Requires |
| - | - |
| Create a browser | `browsers:create` and `browsers:use` on the project or organization, because the response includes connection URLs. Add `profiles:use` on its profile, `profiles:write` if it saves profile changes, `vaults:use` on each linked vault, and `proxies:use` on a saved proxy. |
| Any operation on an existing browser | The browser action, plus `profiles:use` on its attached profile and `vaults:use` on every linked vault. If the browser saves profile changes, `profiles:write` on that profile too. |
| Update a browser | `browsers:write` and `browsers:use`, plus `use` on any profile, vault, or proxy the update adds. |
| Fill from a vault | `vaults:use` on the vault and `browsers:use` on the browser. |
| 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 credential can access, so a credential without a matching grant gets an empty list.

## Not available to credentials with a policy

A credential with a policy gets `403` with `insufficient_scope` on:

* API key management, including creating, listing, rotating, and deleting keys.
* Browser pools.
* Project and organization endpoints, such as listing projects or reading limits.
* Creating browsers that use saved extensions, telemetry export, or app invocations.
* Any other endpoint not covered by the actions above.


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