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

# API keys

> Create, scope, rotate, and revoke company API keys safely.

API keys are the only authentication method for the public developer API. They are created in the dashboard, never through a public endpoint.

## Format

```text theme={null}
Public key: pk_ + 64 hexadecimal characters
Secret key: sk_ + 64 hexadecimal characters
```

The pair is generated with a cryptographically secure random source. The secret is stored as a hash; the full secret is returned only at creation or rotation. If you lose it, rotate the key.

## Creating a key

From the dashboard's API key area for your company:

1. Name the key for the integration it serves.
2. Select scopes. Start from a preset or choose individually.
3. Optionally restrict the key to one or more buckets.
4. Choose an environment label: `development`, `staging`, or `production`.
5. Choose an expiry. The default is 90 days; `null` means no expiry.
6. Complete step-up authentication.
7. Copy both values immediately.

### Prerequisites enforced by the backend

| Requirement | Applies to |
| - | - |
| Company context | All keys on the REST surface |
| `API_PERMISSIONS.MANAGE` | Key creation |
| Active billing access | Key creation |
| Verified email | Trial accounts |
| Step-up authentication | Create, rotate, delete |
| One active key maximum | Trial accounts |
| One active key per bucket maximum | Trial accounts with a bucket scope |

If creation fails, fix the account state. There is no API-side workaround.

## Scope presets

The dashboard offers three convenience presets:

| Preset | Scopes |
| - | - |
| Full Access | `buckets:read`, `buckets:write`, `files:read`, `files:write`, `files:delete`, `folders:read`, `folders:write`, `folders:delete` |
| Read Only | `buckets:read`, `files:read`, `folders:read` |
| Files Only | `buckets:read`, `buckets:write`, `files:read`, `files:write`, `files:delete` |

`mcp` is never included in a preset. Add it explicitly only if you are building an MCP client. See [Scopes and permissions](https://docs.everabyte.com/authentication/scopes-and-permissions.md).

> [!WARNING]
>
> "Full Access" means full access to the storage surface for the buckets the key can see. It does not grant bucket creation, deletion, sharing, billing, or administration.

## Bucket restriction

A key can be unrestricted or limited to specific buckets.

| Configuration | Effect |
| - | - |
| No bucket restriction | Key can target any bucket in the company |
| One or more bucket IDs | Key can target only those buckets |

The restriction is enforced before the operation runs and before trial accounting. Attempts outside the scope return `403 API_BUCKET_SCOPE_DENIED`.

A restricted key can only reach the buckets it is scoped to. It cannot operate on other buckets, and the bucket list shows it only the buckets it is scoped to.

## Environment label

The environment label is metadata recorded with usage events. It does not create a separate API host, dataset, or isolation boundary.

For real isolation, use a separate company workspace with separate keys. This documentation does not describe a sandbox base URL.

## Expiry

`expiresInDays` accepts 1 to 365, or `null` for no expiry. The default is 90 days.

Expired keys fail authentication immediately. There is no grace period documented. Plan rotation before expiry, especially for unattended jobs.

## Rotation

Rotation creates a new public/secret pair for the same key record. Update your deployed secret, verify a request succeeds, then discard the old pair.

A safe sequence:

1. Rotate in the dashboard.
2. Write the new pair to your secret manager.
3. Deploy or restart the consumer.
4. Verify a read request.
5. Confirm no traffic is still using the old pair.

Because the old pair stops working at rotation, plan a short maintenance window or a blue/green deployment where both versions can read the new secret.

## Revocation

Revocation is immediate. Use it when:

* a secret may have leaked,
* an integration is retired,
* a contractor or member loses access,
* usage looks anomalous.

Revoke first, investigate second. Keys cannot be un-revoked; create a replacement.

## Key management through the API

There is no public API-key creation endpoint for developer integrations. Key management routes are session-only and require dashboard privileges plus step-up verification. They are intentionally excluded from this reference.

## Storage guidance

| Do | Do not |
| - | - |
| Store keys in a secret manager | Commit them to Git |
| Inject at runtime | Bake them into container images |
| Use separate keys per service | Share one key across teams |
| Log the key `prefix` only | Log the secret or full headers |
| Rotate on a schedule | Wait for expiry to break production |

## Troubleshooting

| Symptom | Likely cause |
| - | - |
| `401` on every request | Wrong header names, revoked key, expired key, or whitespace in the secret |
| `403 API_COMPANY_ONLY` | Key belongs to an individual account |
| `403 API_BUCKET_SCOPE_DENIED` | Key is restricted to other buckets |
| `403` without a code | Missing scope for the operation |
| `402 SUBSCRIPTION_REQUIRED` | Billing lapsed |
| Creation refused in dashboard | Unverified email, trial key limit, missing permission, or billing state |


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