Access control

Access to the developer API is the product of several independent gates. A request must pass all of them. Understanding the layering makes authorization failures easier to diagnose and keeps a leaked key from becoming a wide-open door.

​

The gates, in order

Gates that run before the handler — 1 through 7 — do not consume trial API quota. That matters when you are debugging: a burst of 403s is not the same as a burst of successful calls.

​

Company boundary

The REST storage API is company-scoped. A key authenticates as the company workspace and can only reach that company’s buckets, folders, and files. Individual EverSpark accounts are rejected at gate 3. The one first-party exception is a device-bound backup key used by the enrolled desktop agent. It is not a general-purpose path for third-party integrations and it cannot be created through the public API.

​

Scopes

Scopes are named capabilities, not HTTP verbs. The set is small on purpose: The bucket scope is a ceiling. A key with files:read but no buckets:read still fails on a file read. In practice, storage scopes come in pairs:

​

Bucket restriction

A key can be unrestricted or limited to explicit bucket IDs.

• Unrestricted: the key can target any bucket in the company, subject to scopes.
• Restricted: the key can target only the listed buckets.

The restriction is enforced before the operation runs and before trial accounting. A restricted key cannot enumerate or reach other buckets: out-of-scope attempts return 403 API_BUCKET_SCOPE_DENIED. This is the single most effective way to limit blast radius. Prefer a per-service key restricted to the buckets that service actually needs.

​

Company roles versus API scopes

Do not confuse them. An API key cannot create or delete buckets, manage sharing, change billing, or administer the company, regardless of scopes. See Scopes and permissions.

​

Step-up authentication

Sensitive account actions require re-verification of the human user:

• creating an API key,
• rotating an API key,
• revoking an API key,
• deleting the account,
• changing password or email.

These actions happen in the dashboard with a browser session, not over the developer API. There is no public endpoint to create a key, so step-up cannot be bypassed programmatically.

​

Session authentication is separate

The dashboard uses browser sessions and JWTs. Those credentials do not authenticate the REST API. Conversely, an API key does not authenticate dashboard routes. This separation is intentional: a stolen browser cookie does not become a machine credential, and a leaked API key does not become a dashboard login.

​

Operational guidance

​

Diagnosing a 403

1. Read the response body. If it has a code, the gate is explicit.
2. No code usually means a missing scope. Compare required scopes for the operation.
3. API_BUCKET_SCOPE_DENIED means the key is restricted to other buckets. Check the bucket ID.
4. API_KEY_SURFACE_DENIED means the route family is not part of the storage surface.
5. API_COMPANY_ONLY means the account is individual, not a company workspace.

​

Related