# Authentication (/docs/authentication)



Authentication [#authentication]

Every request to the SocialCrawl API requires an API key passed via the `x-api-key` header. There is no OAuth flow, no token exchange, and no session — the key is the entire credential.

Getting Your API Key [#getting-your-api-key]

1. Sign up at [socialcrawl.dev](https://www.socialcrawl.dev) — you get 100 welcome credits instantly
2. Navigate to **Dashboard → API Keys**
3. Click **Create Key** and give it a descriptive name (e.g. `production`, `staging`, `local-dev`)
4. Copy the key from the one-time reveal dialog — **this is the only time the full key is shown**

Keys have the format `sc_` followed by 32 random bytes (base64url-encoded), so every key is 46 characters long. Only the last 4 characters are displayed in the dashboard after creation.

Using Your Key [#using-your-key]

Include the `x-api-key` header with every request:

```bash
curl https://www.socialcrawl.dev/v1/tiktok/profile?handle=charlidamelio \
  -H "x-api-key: sc_your_api_key_here"
```

```typescript
const response = await fetch(
  "https://www.socialcrawl.dev/v1/tiktok/profile?handle=charlidamelio",
  { headers: { "x-api-key": "sc_your_api_key_here" } },
);
```

```python
import requests

response = requests.get(
    "https://www.socialcrawl.dev/v1/tiktok/profile",
    params={"handle": "charlidamelio"},
    headers={"x-api-key": "sc_your_api_key_here"},
)
```

Missing or malformed keys return `401 MISSING_API_KEY` / `401 INVALID_API_KEY`. See [Error Handling](/docs/errors.md) for the full list.

Key Management [#key-management]

| Rule                    | Value                                                               |
| ----------------------- | ------------------------------------------------------------------- |
| Active keys per account | Up to 5                                                             |
| Storage                 | SHA-256 hash for auth lookup, AES-256-GCM encrypted for retrieval   |
| Revocation              | Soft delete — revoked keys return `401 INVALID_API_KEY` immediately |
| Expiry                  | Optional per-key `expires_at` (unset = never)                       |
| Credit limit            | Optional per-key spend cap (unset = unlimited)                      |
| Rotation                | Create a new key, update clients, revoke the old one                |

Revoke compromised keys from **Dashboard → API Keys** as soon as possible — a revoked key is rejected on the very next request.

Per-key credit limits [#per-key-credit-limits]

Every key on your account draws on the same credit balance. That is usually what you want — until a test script loops, a CI job misfires, or a new integration is pointed at the wrong endpoint, and the balance your production traffic depends on is gone.

A **credit limit** caps how many credits one key may ever spend. Set one on a key, and that key stops at the cap while every other key on the account keeps working normally.

Set it in **Dashboard → API Keys**. When you create a key, tick **Set a credit limit for this key** and enter a number; leave the box unticked for no limit, which is the default and what a production key normally wants. You can add, change, or remove a limit on an existing key at any time from its ⋯ menu.

```
Production key   no limit          ← your real traffic, unaffected
Test key         500 credit limit  ← stops at 500, whatever it does
```

Once a capped key reaches its limit, its requests return [`402 KEY_BUDGET_EXCEEDED`](/docs/errors.md#key-budget-exceeded) and **nothing is deducted**. Your account balance is untouched, so the rest of your integration keeps running.

A few details worth knowing:

* **The counter is cumulative, not monthly.** It does not reset on its own. When a capped key runs out, raise its limit or hit **Reset usage** to give it the full allowance again.
* **It tracks net spend.** Credits refunded for an upstream failure are also given back to the key's counter, so a run of 404s or 502s never quietly eats a test key's budget.
* **Free calls are free.** Cache hits and zero-cost endpoints do not count against the limit, exactly as they do not count against your balance.
* **Lowering a limit below what a key has already spent is allowed**, and immediately blocks that key. It is the fastest way to stop a key that is misbehaving right now without revoking it and breaking whatever is holding it.
* **The limit applies to the key, not the account.** It is a blast-radius control, not a billing plan — it never changes what you are charged, only which key is allowed to do the charging.

Changes take effect on the key's very next request; there is no cache to wait out.

Security Recommendations [#security-recommendations]

* **Never embed keys in client-side code.** Every request using your key is billed to your account. Use a server proxy when calling from browsers or mobile apps.
* **Use separate keys per environment.** Revoking a staging key shouldn't take down production.
* **Put a [credit limit](#per-key-credit-limits) on non-production keys.** A test or CI key with a cap cannot drain the balance your production traffic runs on, however badly it misbehaves.
* **Store keys in a secret manager** (Vercel Encrypted Env, AWS Secrets Manager, 1Password, etc.) — not in git.
* **Set an `expires_at`** on any key you issue to a contractor or short-lived job.

Related [#related]

* [Credits](/docs/credits.md) — how billing works
* [Response Schema](/docs/response-schema.md) — what comes back
* [Error Handling](/docs/errors.md) — what to do when things break