# API authentication with API keys (https://snitchfeed.com/docs/api/authentication)



Every request needs a Bearer token in the `Authorization` header:

```
Authorization: Bearer <your-api-key>
```

The same header accepts two kinds of token:

* **API keys** (prefix `sf_api_`) for calling the API for your own organization. Covered on this page.
* **OAuth access tokens** for an integration other customers install. See [OAuth](/docs/api/oauth). The credit-metered `POST /v1/data/*` endpoints currently accept API keys only.

Requests without a valid token get `401`. A valid token that lacks the scope for an endpoint gets `403`. Both use the standard [error envelope](/docs/api/introduction#response-format).

## Example [#example]

```bash
curl -sS -X POST "https://api.snitchfeed.com/v1/data/twitter/tweets/search" \
  -H "Authorization: Bearer sf_api_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"query":"example"}'
```

## Create an API key [#create-an-api-key]

1. In SnitchFeed, open **Integrations → API** ([app.snitchfeed.com/integrations/api](https://app.snitchfeed.com/integrations/api)) and stay on the **Keys** tab.
2. Click **Create key**.
3. Give the key a **Name** so you can tell keys apart later.
4. Choose its **Scopes**. All read scopes are ticked by default. Tick `mentions:write` if the key needs to mark mentions seen or engaged. See [scopes](/docs/api/scopes).
5. Click **Create key**, then copy the key from the **Copy your new key** dialog. The full key is shown only once and cannot be retrieved after you close the dialog.

API keys need a plan that includes API access. Without it, the Keys tab shows an upgrade prompt and existing keys are rejected with `403`. This plan check applies to API keys only, not to OAuth tokens.

Building an integration other customers will install? Use [OAuth](/docs/api/oauth) instead of asking them for an API key.

## Revoke or replace a key [#revoke-or-replace-a-key]

Click **Revoke** next to a key on the Keys tab. The key stops working immediately; its usage history is kept. To rotate a key, create a new one, switch your integration to it, then revoke the old one.

## Request history [#request-history]

The **Usage** tab on the same page lists recent API requests with the key, user, route, status, HTTP code and duration of each. Use it to check which key made a call and why it failed.

## Security [#security]

* Store keys in environment variables or a secrets manager, not in source control.
* Give each key only the scopes it needs. A key with `search:read` can spend your organization's credits.
* Each key belongs to one workspace and cannot read another workspace's data.

## Related [#related]

* [API scopes and permissions](/docs/api/scopes): what each scope unlocks
* [API OAuth 2.0](/docs/api/oauth): tokens for integrations other customers install
* [API rate limits](/docs/api/rate-limits): per-minute and in-flight limits
* [API credits](/docs/api/credits): what search calls cost