Authentication
Requests that process data use an API key. Reading tool metadata and running SEO checks does not need one.
API keys
Keys look like sf_live_ followed by 43 URL-safe characters. Create and revoke them from your account, signing in with email and password or Google. Each sign-in session lasts 24 hours; it manages keys and cannot call the API itself.
- The full key is shown once, when it is created. Only a hash and a short prefix are stored.
- A key expires after 90 days. Create a new one before then.
- Revoking takes effect immediately.
Sending a key
Use X-API-Key, or Authorization: Bearer if your client prefers it. A key in the query string is ignored and the request fails with 401.
Either header works
curl "https://api.sadafiles.com/v1/apis/status-and-error-codes" \
-H "X-API-Key: $SADAFILES_API_KEY"
curl "https://api.sadafiles.com/v1/apis/status-and-error-codes" \
-H "Authorization: Bearer $SADAFILES_API_KEY"Scopes
Give each key only what it needs. A request without the right scope fails with 403 FORBIDDEN.
| Scope | Allows |
|---|---|
tools:run | Run tools, pipelines, batches and data APIs |
jobs:read | Read job status, download results, watch progress |
jobs:write | Cancel, continue and delete jobs |
Continuing a job needs both jobs:write and tools:run. A job or batch is visible only to the account that created it; anything else answers 404.
Routes without a key
| Route | Returns |
|---|---|
GET /v1/tools | Every tool the API lists, with option schemas |
GET /v1/tools/:slug | One tool's schema, limits and examples |
GET /v1/formats | Supported conversions and formats |
GET /v1/apis/catalog | The data API catalog |
POST /v1/seo-tools/:slug | SEO checks on public URLs, limited per IP |
GET /v1/privacy/attestation | The running privacy configuration |
Keeping keys safe
Keep keys on your server
Do not put a key in a mobile app or public web page. Anyone who extracts it can use your limits. Read it from an environment variable and revoke it if it leaks.