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

# Scopes and permissions

> The storage-only scope model, how capabilities map to scopes, and how bucket ceilings combine with them.

Every API key carries a set of scopes. Scopes are the only permissions the public API recognizes. Role permissions from the dashboard do not expand API-key access.

## Available scopes

| Scope | Grants |
| - | - |
| `buckets:read` | Read ceiling for files and folders; bucket list and bucket size |
| `buckets:write` | Write ceiling for files and folders, including copy and move |
| `files:read` | List and inspect files, download files, read versions |
| `files:write` | Upload, rename, update metadata, move, copy, restore versions |
| `files:delete` | Soft- and hard-delete files, delete archived versions |
| `folders:read` | List folders, read folder details, subfolders, and content |
| `folders:write` | Create, rename, move, copy folders, restore folders from trash |
| `folders:delete` | Delete folders |
| `mcp` | Authorize the MCP surface only; grants no storage access by itself |

Unknown scopes are rejected. There are no sharing, billing, team, audit, or administration scopes for API keys.

## Capabilities and required scopes

The backend checks a capability, then maps it to scopes. Every listed scope must be present (AND semantics):

| Capability | Required scopes | Used by |
| - | - | - |
| `bucket:read` | `buckets:read` | Bucket list and bucket size |
| `file:read` | `buckets:read` + `files:read` | File lists and metadata |
| `file:download` | `buckets:read` + `files:read` | File stream, version download |
| `file:write` | `buckets:write` + `files:write` | Upload, update, move, copy |
| `file:restore` | `buckets:write` + `files:write` | Restore file from trash, restore version |
| `file:delete` | `buckets:write` + `files:delete` | Delete file, delete version |
| `folder:read` | `buckets:read` + `folders:read` | Folder lists, details, subfolders, content |
| `folder:write` | `buckets:write` + `folders:write` | Create, update, move, copy folder |
| `folder:restore` | `buckets:write` + `folders:write` | Restore folder from trash |
| `folder:delete` | `buckets:write` + `folders:delete` | Delete folder |

Capabilities exercised only by undocumented surfaces are not listed here. Capabilities that are not available to API keys at all — sharing, tags, favorites, audit — are denied even when the key has broad file scopes.

## Bucket scopes are a ceiling

Resource scopes cannot exceed the bucket scope:

```text theme={null}
effective permission = resource scope ∩ bucket scope ∩ key bucket restriction
```

Consequences:

* `files:write` without `buckets:write` cannot upload.
* `folders:delete` without `buckets:write` cannot delete a folder.
* `buckets:read` alone cannot read files, because files also require `files:read`.
* A key restricted to bucket A cannot use any operation against bucket B, regardless of scopes.

Deletion is a common trap: there is no bucket-level delete scope, so file and folder deletion require `buckets:write` as well as the matching `files:delete` or `folders:delete`.

## Presets vs least privilege

| Preset | Suitable for |
| - | - |
| Read Only | Report generators, catalog sync, monitoring |
| Files Only | Upload pipelines that never manage folders |
| Full Access | Trusted internal services that need the whole storage surface |

For production, prefer explicit scopes over presets. Most integrations need one of these combinations:

```text theme={null}
Reader:        buckets:read, files:read, folders:read
Uploader:      buckets:read, buckets:write, files:read, files:write, folders:read, folders:write
Lifecycle job: buckets:read, buckets:write, files:read, files:write, files:delete, folders:read, folders:write, folders:delete
```

## The `mcp` scope

`mcp` is an integration flag, not a data permission. A key with only `mcp` can complete the MCP handshake but cannot read or write storage. MCP access also requires a paid subscription. See [MCP server](https://docs.everabyte.com/integrations/mcp.md).

## Changing scopes

Scopes are changed in the dashboard. A change takes effect on the next request; there is no cached token to expire.

Removing a scope can break a running integration immediately. Treat scope changes like a deployment: announce them, update the consumer first where possible, then narrow the key.

## Diagnosing permission failures

| Response | Meaning |
| - | - |
| `403` without a stable code | Missing capability or scope |
| `403 API_BUCKET_SCOPE_DENIED` | Bucket is outside the key's scope |
| `403 API_KEY_SURFACE_DENIED` | Route family is not available to API keys |
| `401` | Key pair invalid, expired, or revoked |

Permission checks happen before the operation. A `403` does not mean the resource exists or does not exist.

## Verify a key's effective access

There is no public endpoint that returns a key's scopes. Verify behavior with reads:

1. `GET /buckets/all` — proves `buckets:read`.
2. `GET /folders/findAll/{bucketId}` — proves `buckets:read` + `folders:read`.
3. `GET /files/findAll/{bucketId}` — proves `buckets:read` + `files:read`.

Write access must be tested against a disposable resource, not production data.


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