Authentication

Overview

The India Energy Atlas API uses a simple header-based authentication model. There is one credential — the API key — and it is carried in every request.

Creating keys

1. Sign in and open Settings → API Keys.
2. Click Generate key and give it a human-readable name (e.g. "prod-etl", "laptop-dev").
3. Copy the full secret shown in the modal. It is displayed once. The server stores only a hash and cannot show it to you again.

Using keys

Pass the key in the X-API-Key header of every request. Do not put the key in the URL, query string, or body — those leak into logs and referrers.

export ATLAS_API_KEY="iea_live_YOUR_KEY"

curl -H "X-API-Key: ${ATLAS_API_KEY}" \
  "https://api.energymap.in/developer/v1/ping"

IP allow-lists

On Starter and above, you can scope a key to a comma-separated list of source IPv4 addresses or CIDR blocks. Requests from any other IP return 403 ip_not_allowed.

POST /api/developer/keys
Authorization: Bearer <clerk-jwt>
Content-Type: application/json

{
  "name": "prod-etl",
  "ip_allow_list": ["203.0.113.42", "203.0.113.64/29"]
}

Rotating & revoking

• Rotate: generate a new key, deploy it, then revoke the old one. No window of rejection — both keys work until you revoke.
• Revoke: takes effect immediately. Revoked keys return 401 api_key_revoked. Revocation is permanent — you cannot un-revoke a key.
• Expiration: keys may have an optional expires_at. Expired keys return 401 api_key_expired.

Security checklist

• Never commit keys to git. Use .env files gitignored, secrets managers (Vault, Doppler, Secrets Manager), or CI secret stores.
• Pin server-side keys to their egress IP.
• Rotate keys on a schedule — quarterly for low-value, monthly for anything sensitive.
• Revoke immediately on employee offboarding or suspected compromise.
• Never embed keys in client-side JavaScript, mobile apps, or browser extensions — the key is visible to the user and anyone intercepting traffic.