Guide
Authentication
Send your API login and an API key with every request, using HTTP Basic authentication — the scheme every HTTP client supports out of the box. Only access requests and the public reference endpoints (marketplaces, status and status codes) work without a key.
HTTP Basic
Join your login and key with a colon, encode the result as Base64 and send it in the Authorization header:
Authorization: Basic base64("<login>:<api_key>")Most tools do this for you: curl --user login:key, requests.get(url, auth=(login, key)) in Python, or a manually built header in JavaScript. To build the header yourself in a shell (the tr step matters: GNU base64 on Linux wraps its output after 76 characters, which would put a line break into the header):
AUTH=$(printf '%s' "$API_LOGIN:$API_KEY" | base64 | tr -d '\n')
curl --header "Authorization: Basic $AUTH" https://api.screamingdata.dev/Bearer key
The API key alone also identifies your account. If your client prefers bearer tokens, send the key without the login:
Authorization: Bearer sd_live_…your key…API keys
- Keys look like
sd_live_followed by 40 URL-safe characters. - The full key is shown once, when it is created. Only a hash of it is stored, so a lost key cannot be recovered — create a new one and revoke the old one.
- An account can have up to 20 active keys. Use one per environment or service so you can rotate them independently.
- Create keys with POST /v1/appendix/keys, list them (prefix and last four characters only) with user_data, and revoke them with DELETE /v1/appendix/keys/{key_id} — or do all of it in the dashboard.
- A revoked key stops working immediately.
Authentication errors
Authentication problems are reported at the request level with HTTP 401 and one of these codes in status_code:
| Code | Message | HTTP | When |
|---|---|---|---|
| 40100 | Authentication failed. | 401 | The Authorization header is missing or malformed, or the login and API key do not match. |
| 40101 | API key revoked. | 401 | The API key was revoked. Use another active key or create a new one. |
| 40102 | Account disabled. | 401 | The account is disabled. Contact support. |
Keeping keys safe
- Call the API from your server. Never ship a key in browser JavaScript, a mobile app or a public repository.
- Store keys in environment variables or a secret manager, not in source code.
- Rotate keys regularly: create a new key, deploy it, then revoke the old one.
- Revoke a key immediately if it may have leaked, then check recent usage in the dashboard.
- Always use HTTPS so credentials are never sent in clear text.
Suspect a leaked key?