# API keys

Every API request needs an API key. Create keys in the dashboard under **API keys**, or through the API with a full-access key.

## Using a key

Send the key as a bearer token:

```
Authorization: Bearer sg_live_...
```

Keys are secret. Use them only from your server, never in a browser or a mobile app. The full key is shown once, when you create it. After that, Spamgone shows only a short prefix such as `sg_live_AbCd`, and stores nothing that can be turned back into the key.

## Modes

| Mode   | Prefix     | What it does                                                                               |
| ------ | ---------- | ------------------------------------------------------------------------------------------ |
| `live` | `sg_live_` | Real checks, counted toward your plan.                                                     |
| `test` | `sg_test_` | Fixed results that are never counted and never call the AI model. For building and for CI. |

A test key can only create, rotate or revoke other test keys, so a leaked one can't affect live traffic.

## Permissions

| Permission    | Allowed                                                                                        |
| ------------- | ---------------------------------------------------------------------------------------------- |
| `full_access` | Every team endpoint that isn't for admins only, including managing keys.                       |
| `check_only`  | Creating checks, sending feedback on its own checks, and the Perspective-compatible endpoints. |

Give the key inside your app `check_only`, so a leak can't be used to read your history or manage your account.

## Managing keys through the API

All of these need a full-access key.

| Method and path                 | What it does                                                                                                                                    |
| ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `POST /v1/api-keys`             | Creates a key from `name`, `mode` (default `live`) and `permission` (default `full_access`). The response includes `token`, the full key, once. |
| `GET /v1/api-keys`              | Lists the keys that still work, with `prefix`, `last_used_at` and `request_count`.                                                              |
| `DELETE /v1/api-keys/{id}`      | Revokes a key. It stops working within a minute.                                                                                                |
| `POST /v1/api-keys/{id}/rotate` | Creates a new key with the same name, mode and permission. Send `overlap_seconds` (up to 86400) to keep the old key working that long.          |

Each plan sets how many keys that still work a team can have: 25 on Free and Pro, 100 on Scale, and no limit on Enterprise. People must verify their email address before they create keys.

## Usage

`last_used_at` and `request_count` update within a minute of each request.

## Errors

| `name`                  | Status | Meaning                                                          |
| ----------------------- | ------ | ---------------------------------------------------------------- |
| `missing_api_key`       | 401    | No key was sent in the `Authorization` header.                   |
| `invalid_api_key`       | 403    | The key is unknown, revoked or past its rotation overlap.        |
| `restricted_api_key`    | 403    | The key's permission or mode doesn't allow this request.         |
| `api_key_limit_reached` | 422    | The team already has the most keys its plan allows.              |
| `email_not_verified`    | 403    | The person creating the key hasn't verified their email address. |
