> ## Documentation Index
> Fetch the complete documentation index at: https://api.specter.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Authenticate Specter API Requests with Bearer Keys

> Learn how Specter API keys work, how to send them as bearer tokens, which permissions each endpoint needs, and how organization quotas are shared.

The Specter API authenticates every request with an API key sent as a bearer token. Each key belongs to one organization and only works for the permissions explicitly granted to it.

## Send your API key

Include your key in the `Authorization` header:

```bash theme={null}
curl "https://staging.specter.co/api/v1/platform-health" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

<Warning>
  Keep API keys secret. Do not commit them to source control or use them in client-side code.
</Warning>

## Permissions

API keys need an explicit permission for each operation. If a key lacks the permission, or belongs to a different organization, the request returns `403` with the `insufficient_scope` error code.

| Endpoint | Required permission |
| - | - |
| `GET /api/v1/sites` | `sites:read` |
| `GET /api/v1/sensors` | `sensors:read` |
| `GET /api/v1/workflows` | `workflows:read` |
| `GET /api/v1/alerts/summary` | `alerts.summary:read` |
| `GET /api/v1/platform-health` | `platform.health:read` |

## Quotas and rate limits

Every key in an organization draws from the same quota for each operation. When a key's admission limit or the organization's quota runs out, the API returns `429` with the `rate_limited` error code and a `Retry-After` header that gives the number of seconds to wait. See [Errors](/api-reference/errors).

## Authentication errors

| Status | Code | Cause |
| - | - | - |
| `400` | `invalid_request` | The credential is malformed or sent more than once. |
| `401` | `invalid_api_key` | The key is missing, invalid, expired, or revoked. |
| `403` | `insufficient_scope` | The key belongs to another organization or lacks the required permission. |


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