Scopes and permissions

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:

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:

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.

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:

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

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

Getting Started

Core Concepts

Authentication & Security

Storage Guides

Error Handling

Security & Data Protection

Enterprise & Partners

Resources

Available scopes

Capabilities and required scopes

Bucket scopes are a ceiling

Presets vs least privilege

The `mcp` scope

Changing scopes

Diagnosing permission failures

Verify a key’s effective access

​Available scopes

​Capabilities and required scopes

​Bucket scopes are a ceiling

​Presets vs least privilege

​The mcp scope

​Changing scopes

​Diagnosing permission failures

​Verify a key’s effective access

Available scopes

Capabilities and required scopes

Bucket scopes are a ceiling

Presets vs least privilege

The `mcp` scope

Changing scopes

Diagnosing permission failures

Verify a key’s effective access