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

> The headers the REST API expects, and why browser sessions are a different surface.

## Headers

Every request to the storage API carries both keys:

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

| Header | Required | Notes |
| - | - | - |
| `X-Public-Key` | Yes | Identifies the key record |
| `X-Secret-Key` | Yes | Proves possession; stored as a hash server-side |
| `Authorization` | No | Not used by this surface |
| `Content-Type` | For JSON bodies | `application/json` |
| `Content-Type` | For uploads | `multipart/form-data` with a boundary |

> [!WARNING]
>
> Do not send a dashboard `Authorization: Bearer` token to the storage API. Session tokens belong to the web application surface and will not authenticate these routes.

## 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"
```

## Where keys come from

Keys are created in the dashboard, under the company's API key area. Creation requires:

* company context,
* the permission to manage API keys,
* active billing access,
* a verified email on trial accounts,
* step-up authentication.

There is no public endpoint to create, rotate, or revoke a key. See [API keys](https://docs.everabyte.com/authentication/api-keys.md).

## Which surface am I on?

| Surface | Credential | Routes |
| - | - | - |
| REST storage API | `X-Public-Key` + `X-Secret-Key` | `/files`, `/folders`, `/buckets` (documented subset) |
| Dashboard / web app | Browser session and JWT | UI routes and session-only endpoints |

The API key is a machine credential. The browser session is a human credential. They do not substitute for one another.

## Company scope

A key authenticates as its company workspace. It cannot reach another company's resources, even with a valid bucket ID.

Individual EverSpark accounts are refused with `403 API_COMPANY_ONLY`. The single first-party exception is a device-bound backup key used by the enrolled desktop agent.

## Server-side only

API-key headers are **not** allowed by CORS. A browser fetch from another origin that includes these headers will fail preflight.

This is deliberate: an API key embedded in a browser bundle is a leaked key. Proxy requests through your server if you need a browser front end.

See [Requests and CORS](https://docs.everabyte.com/authentication/requests-and-cors.md) for details.

## Failure modes

| Status | Meaning |
| - | - |
| `401` | Missing header, malformed key, revoked key, or expired key |
| `403 API_COMPANY_ONLY` | Key belongs to an individual account |
| `403 API_KEY_SURFACE_DENIED` | Route family is not available to API keys |
| `403 API_BUCKET_SCOPE_DENIED` | Key is restricted to other buckets |
| `402 SUBSCRIPTION_REQUIRED` | Billing lapsed |
| `403 TRIAL_API_LIMIT_REACHED` | Trial call quota exhausted |

## Related

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

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

> **[Requests and CORS](https://docs.everabyte.com/authentication/requests-and-cors.md)**
>
> Why this is server-side only.

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


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