> ## Documentation Index
> Fetch the complete documentation index at: https://docs.oleander.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Permissions

> Define allowed actions, choose their scope, and delegate access through roles.

A permission allows one action on a resource within a scope. Add permissions when creating a role or through its **Permissions** action in [Settings → Organization → Roles](https://oleander.dev/app/settings/roles).

| Field         | Meaning                                    | Example                      |
| ------------- | ------------------------------------------ | ---------------------------- |
| Resource type | The kind of resource being controlled.     | Compute                      |
| Scope         | Which resources the permission applies to. | Selected resources: `duckdb` |
| Actions       | What the principal may do.                 | Execute                      |

Selecting multiple resources and actions creates a permission for each resource/action combination. Every permission is **Allow**; explicit Deny permissions are not supported. A definition can be shared by several roles, but has no effect until attached to a role assigned to a principal.

## Choosing a scope

Broad scopes such as **All engines**, **Entire warehouse**, and **All application principals** include matching resources created later. **Selected resources** refers to the chosen objects; **Selected namespaces** selects warehouse namespaces.

**Self (whoever holds this role)** means the principal making the request, including an API key's owner. It does not mean the role's creator. For **API keys**, selecting a principal scopes the permission to that principal's keys.

The available actions change with the scope. For example, creating an Application principal requires **All application principals**; a selected Application principal can be deleted but is already created. Available resource choices also depend on the caller's discovery access.

## Delegating access

**Manage grants** permits delegation within its scope, including delegation of **Manage grants** itself. It does not automatically grant operational actions such as **Execute** or **Describe**.

| Operation                             | Required authority                                                                              |
| ------------------------------------- | ----------------------------------------------------------------------------------------------- |
| Assign or unassign a role             | Manage grants on **both** the target principal and role.                                        |
| Attach or detach a permission         | Manage grants on **both** the target role and the resource the permission controls.             |
| Invite a Human with roles             | Invite for All human principals, plus Manage grants on each selected role.                      |
| Configure another execution principal | Describe and Manage grants on that principal, plus its eligibility for the requested operation. |

Permission definitions are themselves manageable resources. **Manage grants** on a permission definition does not substitute for authority over the compute engine, warehouse, or other resource it describes.

A grant for selected resources cannot delegate authority over all resources. Oleander's namespace delegation check matches the selected namespace exactly, or **Entire warehouse**: authority to attach permissions for `finance` does not authorize attaching permissions for `finance.staging`.

Warehouse **Pass grants** permits delegation of held warehouse privileges, excluding Pass grants itself. It does not replace the Manage grants requirements for attaching permissions to oleander roles. Warehouse data inheritance is explained in the [reference](/iam/resources-and-actions#warehouse).

## Example: query one namespace

These permissions combine compute execution with read access to an existing namespace:

| Resource type | Scope                          | Actions |
| ------------- | ------------------------------ | ------- |
| Compute       | Selected resources: `duckdb`   | Execute |
| Warehouse     | Selected namespaces: `finance` | Select  |

Attach both to a custom role and assign the role to the intended principal. They allow DuckDB execution and reads within `finance`; they grant neither data modification nor job cancellation. Other assigned roles may grant additional access.

Catalog discovery and credential retrieval have separate **Catalogs → Describe** requirements. Add those grants when the workflow needs them; compute execution alone does not supply them.

Use [Resources and actions](/iam/resources-and-actions) to choose the precise scope and actions for each permission.