Getting Started

Authentication

All requests are authenticated with an API key passed in the X-API-Key header. Keys are tier-scoped, rotatable, and can be optionally restricted to a list of source IPs.

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.

Aspect	Details
Header	`X-API-Key`
Key format	`iea_live_<random-32-char>`
Storage	Only the SHA-256 hash is kept server-side. You see the secret once.
Tier binding	Tier is attached to the key record, not the key string.
Rotation	Instant revoke + regenerate from Settings.

Creating keys

Sign in and open Settings → API Keys.
Click Generate key and give it a human-readable name (e.g. "prod-etl", "laptop-dev").
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.

Use separate keys per environment

Keep dev, staging, and prod on different keys so you can revoke one without taking the others down. One-to-one key-per-machine also makes IP allow-listing tractable.

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.

bash

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.

When to use it

Server-to-server keys (ETL, cron jobs, backends) have a fixed egress IP — pin them. For keys used from laptops, CI runners, or dynamic cloud IPs, leave the allow-list empty.

http

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.

No browser-safe key

There is no "publishable" variant of the key. Every key has the full tier's quota — treat all keys as server-side secrets.

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.

Aspect	Details
Header	`X-API-Key`
Key format	`iea_live_<random-32-char>`
Storage	Only the SHA-256 hash is kept server-side. You see the secret once.
Tier binding	Tier is attached to the key record, not the key string.
Rotation	Instant revoke + regenerate from Settings.

Creating keys

Click Generate key and give it a human-readable name (e.g. "prod-etl", "laptop-dev").

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.

Use separate keys per environment

Keep dev, staging, and prod on different keys so you can revoke one without taking the others down. One-to-one key-per-machine also makes IP allow-listing tractable.

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.

bash

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.

When to use it

Server-to-server keys (ETL, cron jobs, backends) have a fixed egress IP — pin them. For keys used from laptops, CI runners, or dynamic cloud IPs, leave the allow-list empty.

http

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.

No browser-safe key

There is no "publishable" variant of the key. Every key has the full tier's quota — treat all keys as server-side secrets.