Skip to content
GridCapacityAPI.com

Start

Authentication

Bearer keys, live and test keys, and which routes answer without one.

Bearer keys

Send your key on every request to a data route, as a bearer token in the Authorization header.

curl "https://api.gridcapacityapi.com/v1/sources" \  -H "Authorization: Bearer gc_live_..."

X-API-Key: gc_live_... works too, for tools that cannot set an Authorization header. A missing, malformed or revoked key is 401 unauthorized. The response never says which of the three, because that would tell someone guessing keys how close they are.

Live and test keys

  • gc_live_… and gc_test_… keys reach exactly the same data and are metered the same way, against your monthly quota and your rate limit.
  • The label is yours: use test keys for CI and local development so their usage is told apart from production’s in the dashboard.

The secret is shown once, when the key is created. Only its SHA-256 is stored; there is no endpoint that can return a secret, so a lost key is revoked and replaced.

Keep keys on the server

A key in browser JavaScript is a key anyone can copy and spend. Call the API from your backend, and give your front end only what it needs to render.

Routes that need no key

RouteWhat it is for
GET /v1/healthStatus and version.
GET /v1/plansPlans, prices and what each allows.
GET /v1/openapi.jsonThe OpenAPI 3.1 contract.
GET /v1/coverageWhat is covered, per country.
GET /v1/assets.geojsonAsset points for a map, no values. Rate-limited per address.
GET /v1/tiles/assets/{z}/{x}/{y}.mvtThe same points as vector tiles.

Checking a key

GET /v1/key answers with the calling key’s plan, its limits and this month’s usage — useful as a health check in your own deployment.

curl "https://api.gridcapacityapi.com/v1/key" -H "Authorization: Bearer gc_live_..."