Understanding API Keys & Authentication
Authentication is a critical component of interacting with SdashAPI. Because our infrastructure handles millions of past questions and serves a large volume of traffic across Africa, we must strictly control access to our resources. This guide will walk you through exactly how our authentication system operates, the technical reasoning behind our design choices, and the industry-standard best practices for keeping your access credentials secure while building your educational applications.
How Stateless Authentication Works
1.4.1SdashAPI utilizes a simple, highly scalable, stateless API key mechanism. In traditional web development, a server might remember you using a "session" or a "cookie" after you log in. However, RESTful APIs like SdashAPI operate differently: every single request you send to our server must be completely self-contained and independently verifiable.
Whenever you make an HTTP request to any of our endpoints, our servers intercept the request and immediately check for the presence of a specific HTTP header containing your unique API key. If the key is valid and belongs to an active account, the server processes your request and returns the requested examination data.
The AccessToken Header
1.4.2To successfully authenticate, you must manually include your API key in the headers of your HTTP request. While some platforms utilize the standard Authorization: Bearer <token> syntax or require basic HTTP authentication, SdashAPI uses a custom, explicit header specifically named AccessToken. This makes our requests extremely straightforward to construct in any programming language.
Here is an example of what the raw HTTP request headers look like when correctly formatted:
GET /api/v1/q?type=utme&subject=mathematics HTTP/1.1 Host: sdashapi.com Accept: application/json AccessToken: YOUR_UNIQUE_API_KEY_HERE
Securing Your Keys in Production
1.4.3Because your API key grants direct access to your account and quota, it must be treated like a password. You should never commit your API key to a public GitHub repository, and you should avoid embedding it directly into frontend code that is shipped to a user's browser.
Instead, store your API keys as Environment Variables (like in a .env file) on your secure backend server. Your frontend applications should send requests to your own server, which will then append the API key and forward the request to SdashAPI securely behind the scenes.
Handling Authentication Errors
1.4.4When integrating the API, you may occasionally run into authentication issues. The system provides clear HTTP status codes to help you debug what went wrong:
- 401 Unauthorized: This means you did not provide the
AccessTokenheader at all, or the header name was misspelled. - 403 Forbidden: This occurs when you provide a header, but the API key value is completely invalid or belongs to a suspended account.
- 429 Too Many Requests: This indicates that your key is valid, but you have exceeded your monthly request quota based on your current subscription tier.
Rolling Your API Keys
1.4.5If you suspect that your API key has been compromised (for example, if you accidentally pushed it to a public GitHub repository), you should immediately revoke it and generate a new one.
You can do this directly from your Developer Dashboard. Clicking the "Regenerate Key" button will instantly invalidate your old key, blocking any future requests that use it. You will then receive a brand new key that you can swap into your production environment to restore secure access.
Quota Management and Billing
1.4.6Every API key generated on SdashAPI is permanently tied to a specific developer account and subscription plan. These plans dictate exactly how many requests you are permitted to make per month. By requiring an API key for every single request, our backend analytics system can accurately and transparently track your usage in real-time. You can monitor your consumption, view historical traffic graphs, and manage your billing by visiting your dashboard.