API authentication with API keys

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

Example

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

1. In SnitchFeed, open Integrations → API (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.
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 instead of asking them for an API 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

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

• 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

• API scopes and permissions: what each scope unlocks
• API OAuth 2.0: tokens for integrations other customers install
• API rate limits: per-minute and in-flight limits
• API credits: what search calls cost