Authentication and keys
Every request carries your key in the x-api-key header:
curl "https://api.socialscrape.io/v1/account/credits" \
-H "x-api-key: $SOCIALSCRAPE_API_KEY"A key is never accepted in the query string, so it cannot end up in a log or a browser history.
Key format#
Live keys look like ss_live_ followed by 40 letters and digits. Test keys start with ss_test_. Treat both as passwords.
Create, rotate and revoke#
Keys belong to a team, not to a person, and are managed in the dashboard.
- Give each key a name, one per app or environment, so you can see what uses it.
- The full key is shown once, when you create it. We store only a hash, so we cannot show it again; if you lose it, create a new one.
- The dashboard shows when each key was last used.
- To rotate a key, create the new one, deploy it, then revoke the old one. A team can hold up to 20 active keys.
- A revoked key stops working within seconds.
Owners and admins can create and revoke keys. Members can see key names but not make changes; see Teams.
What a bad key returns#
| Situation | Answer |
|---|---|
| Header missing, key malformed, unknown or revoked | 401 unauthorized |
| The key or its team is suspended | 403 forbidden |
| The team has too few credits | 402 insufficient_credits |
A missing, malformed and revoked key all answer the same way on purpose, so an error never tells a stranger which keys exist.
Keep keys out of code#
- Read the key from an environment variable or a secrets manager. Never commit it.
- Call the API from your server. A key in browser or mobile code is public.
- If a key leaks, revoke it in the dashboard first, then create a replacement.
Agents that pay for themselves#
An AI agent holding a key with no credits can buy a pack over HTTP, with no dashboard. See Credits and pricing.