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

# Authentication overview

> How requests to the Everabyte developer API are authenticated, and how that differs from dashboard sessions.

Everabyte has two authentication surfaces. They do not substitute for each other.

| Surface | Mechanism | Use it for |
| - | - | - |
| REST storage API | API key pair in headers | Server-side integrations |
| Dashboard and web app | Browser session / JWT | Human users |

This documentation covers the first. The second is handled by the application and is not a public API contract.

## API key headers

Every request to the developer API must include both headers:

```http theme={null}
X-Public-Key: pk_<64 hexadecimal characters>
X-Secret-Key: sk_<64 hexadecimal characters>
```

Example:

```bash theme={null}
curl "https://api.everabyte.io/api/files/findAll/BUCKET_ID?page=1&limit=20" \
  -H "X-Public-Key: $EVB_PUBLIC_KEY" \
  -H "X-Secret-Key: $EVB_SECRET_KEY"
```

The server verifies the pair cryptographically. Key prefixes are not trusted as proof of anything.

## What the key represents

An API key authenticates a **company context**. Requests act on that company's buckets, folders, and files. The key may also be assigned to a specific member, in which case the effective user context is that member.

Keys are limited to the storage surface and to the backup agent routes:

```text theme={null}
/files/*   /folders/*   /buckets/*   /backup/jobs/*   /backup/runs/*   /backup/agent/*
```

This reference documents the file and folder operations plus two read-only bucket operations (list and size). Other bucket and backup routes are reachable with a key but are not part of this contract.

Anything else is rejected with `403 API_KEY_SURFACE_DENIED` before trial accounting runs.

## Key lifecycle

| Stage | Where | Notes |
| - | - | - |
| Create | Dashboard | Requires company context, key-management permission, active billing, and step-up authentication |
| View | Dashboard | Secret is not retrievable after creation |
| Use | REST API | Headers on every request |
| Rotate | Dashboard | Produces a new pair; requires step-up |
| Revoke | Dashboard | Immediately stops authentication |
| Expire | Automatic | Expiry is set at creation; default 90 days |

Trial accounts must also have a verified email and may hold only one active key.

## Authentication failures

Missing or invalid credentials return `401` through the controller error shape:

```json theme={null}
{
  "status": 401,
  "message": "Invalid API key.",
  "error": null
}
```

Expired keys, revoked keys, and suspended keys also fail authentication. The message text is localized; do not branch on it.

Policy failures that occur after authentication use a stable `code`:

| Code | Status | Meaning |
| - | - | - |
| `API_COMPANY_ONLY` | 403 | Key is not a company key and is not a device-bound key |
| `API_KEY_SURFACE_DENIED` | 403 | Route is outside the storage surface |
| `API_BUCKET_SCOPE_DENIED` | 403 | Target bucket is outside the key's scope |
| `API_KEY_RATE_LIMITED` | 429 | Per-key rate limit exceeded |
| `SUBSCRIPTION_REQUIRED` | 402 | No active subscription |
| `TRIAL_API_LIMIT_REACHED` | 403 | Trial call quota exhausted |
| `DEVICE_BLOCKED` | 403 | The key's backup device was blocked by an administrator |

A missing scope is a `403` from the capability guard. It does not carry one of the stable codes above, so treat any 403 without a known code as a permission problem.

## Server-side only

API key headers are not allowed by the API's CORS configuration. A browser request that includes them will fail preflight before it reaches a route.

> [!TIP]
>
> Call the API from your backend, a queue worker, or a scheduled job. If a browser needs data, have your backend proxy the request and enforce your own authorization.

## What not to do

* Do not put keys in client-side JavaScript, mobile app binaries, or public repositories.
* Do not share one key across unrelated services.
* Do not use a key with broader scopes than the integration needs.
* Do not log the secret or full header values.
* Do not assume a dashboard session can call the REST API.

## Next

> **[API keys](https://docs.everabyte.com/authentication/api-keys.md)**

> **[Scopes and permissions](https://docs.everabyte.com/authentication/scopes-and-permissions.md)**

> **[Requests and CORS](https://docs.everabyte.com/authentication/requests-and-cors.md)**

> **[Rate limits](https://docs.everabyte.com/authentication/rate-limits.md)**


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