Skip to main content
Sorsa API uses API keys to authenticate requests. Your API key grants full access to your account and quota, so treat it like a password.

​
How authentication works

Every request to the Sorsa API must include your API key in the ApiKey header. Use the header name exactly as shown.
If the header is missing, misspelled, or contains an invalid key, the API returns an error (see Troubleshooting below). Example request
For POST endpoints, also include the Content-Type header:
Tip: You can test your API key without writing any code using the API Playground.

​
Request requirements

Every API call must meet the following requirements: HTTPS only. All requests must use https://. Plain HTTP requests will be rejected. ApiKey header. Required on every request. No OAuth, no bearer tokens, no query parameter authentication. Content-Type header. Required for POST requests. Set it to application/json and pass parameters as a JSON body. HTTP methods. Endpoints use either GET or POST depending on the operation. The API Reference specifies the method for each endpoint.

​
Managing your API keys

Find your key. Your active API key is displayed on the Dashboard overview page. New accounts include 100 free requests, so your first key works right away with no card on file. Create or delete keys. To generate a new key or revoke an existing one, go to the API Keys section in your dashboard. Monitor usage. You can track your request history and remaining quota on the Usage stats page or programmatically via the GET /key-usage-info endpoint.
Important: When you delete or replace a key, any application still using the old key will immediately start receiving 401 Unauthorized errors. Update your integrations before revoking a key.

​
Security best practices

Never expose your key in client-side code. Do not call the Sorsa API directly from browsers, mobile apps, or any frontend environment. Your API key would be visible in browser dev tools, network logs, and source code. Always route requests through your own backend server. Use environment variables. Store your key in .env files or your platform’s secrets manager (AWS Secrets Manager, Vercel Environment Variables, Railway Variables, and similar). Never hardcode keys in source files. Keep keys out of version control. Add .env to your .gitignore. Never commit API keys to public or private repositories on GitHub, GitLab, or Bitbucket. Rotate compromised keys immediately. If you accidentally expose your key in a commit, a screenshot, or a public forum, go to the API Keys section, delete the compromised key, and generate a new one. The old key stops working instantly.

​
Troubleshooting

401 Unauthorized The ApiKey header is missing, the header name is misspelled, or the key has been deleted or was never valid. Double-check that your header is exactly ApiKey (not Api-Key or Authorization). 403 Forbidden Your key is valid, but your subscription has expired or your monthly request quota is exhausted. Check your remaining balance on the Dashboard or by calling GET /key-usage-info. 429 Too Many Requests You are sending requests faster than the rate limit allows (a flat 20 requests per second on every plan). Add a short backoff between calls and retry. See Rate Limits for details and retry strategies. CORS errors in the browser If you see CORS-related errors, you are likely calling the API from frontend JavaScript. Sorsa API is designed for server-side use only. Move your API calls to a backend service or serverless function.

​
Next steps