Getting started
Authentication
Every request must carry an API key. Keys are created in your dashboard under API Keys and are shown exactly once, at creation.
Sending the key
Either header works. Pick one and use it consistently.
X-API-Key: YOUR_API_KEYAuthorization: Bearer YOUR_API_KEYExample
curl "https://address.s2coder.com/api/v1/address/autocomplete?q=gomti+nagar" \
-H "X-API-Key: YOUR_API_KEY"How keys are stored
We store a SHA-256 hash of your key, plus its first twelve and last four characters for display. The secret itself is never written to our database, so it cannot be recovered — not by you, and not by us. If you lose a key, regenerate it: the name, limits and usage history are kept while the secret is replaced.
Restricting a key
- IP allowlist — limit a key to specific source addresses. Requests from anywhere else get
403. - Expiry — set a date after which the key stops working.
- Per-key limits — override the plan quota on a single key, for example to cap a staging integration.
Authentication errors
| Status | Code | Meaning |
|---|---|---|
| 401 | unauthenticated | No key sent, or the key is not recognised. |
| 403 | forbidden | Key is revoked, expired, IP-blocked, or the owning account is suspended. |
Keeping keys safe
- Never embed a key in front-end JavaScript or a mobile app — call the API from your server.
- Never commit a key to version control. Use an environment variable.
- Use separate keys per environment so one can be revoked without downtime elsewhere.
- Rotate immediately if a key is exposed. Revocation takes effect on the next request.