# Authentication

Most routes need an API key. A key issued on this site belongs to the whole organization.

## Sending the key

The API reads the key from one of 3 places:

| How | Example | Note |
|---|---|---|
| `Authorization: Bearer <key>` | `curl -H "Authorization: Bearer $SECBLAST_API_KEY" 'https://api.secblast.com/v3/filings?limit=1'` | Preferred. |
| `X-API-Key: <key>` | `curl -H "X-API-Key: $SECBLAST_API_KEY" 'https://api.secblast.com/v3/filings?limit=1'` | Equivalent to the Bearer header. |
| `?api_key=<key>` | `curl 'https://api.secblast.com/v3/filings?limit=1&api_key='"$SECBLAST_API_KEY"` | The key is part of the URL. |

```bash
curl -sS -H "Authorization: Bearer $SECBLAST_API_KEY" \
  'https://api.secblast.com/v3/filings?limit=1'
```

## When the key is missing or wrong

The API answers `401` with a problem body whose `code` is `unauthorized` and a `WWW-Authenticate: Bearer` header. The same answer is given for a missing key, an unknown key and a key that is not active. See [Errors](https://www.secblast.com/docs/errors).

## Getting and managing keys

- Your first key is created when you [sign up](https://www.secblast.com/signin). Create, rename, rotate and revoke keys under [API keys](https://www.secblast.com/dashboard/keys).
- Keys issued on this site look like `sbk_` followed by 32 letters and digits.
- A key belongs to an organization, not to a person.
- Rotating a key creates a replacement, and the old key keeps working for a grace period.
- Revoking a key stops it at once.
- The API allows cross-origin requests, so a browser can call it directly; the [console](https://www.secblast.com/console) does.
