Skip to main content

​
How to Authenticate Requests to the Sorsa API

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. The header name is case-sensitive. 
ApiKey: your_api_key_here
If the header is missing, misspelled, or contains an invalid key, the API will return an error (see Troubleshooting below). Example request 
curl --request GET \
  --url 'https://api.sorsa.io/v3/info?username=elonmusk' \
  --header 'ApiKey: YOUR_API_KEY'
For POST endpoints, also include the Content-Type header: 
curl --request POST \
  --url 'https://api.sorsa.io/v3/search-tweets' \
  --header 'ApiKey: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{"query": "bitcoin", "order": "popular"}'
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. 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 will 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, etc.). 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 will stop working instantly.

​
Troubleshooting

401 Unauthorized The ApiKey header is missing, the header name is misspelled (it is case-sensitive), or the key has been deleted or was never valid. Double-check that your header is exactly ApiKey (not Api-Key, apikey, or Authorization). 403 Forbidden Your key is valid, but your subscription has expired or your request quota is exhausted. Check your remaining balance on the Dashboard or by calling GET /key-usage-info. 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