Authentication

The API is in early access and is not publicly available. Endpoint URLs, request examples and sample responses on this page are illustrative. Contact hello@vangrid.io to request access.

Every request to the Vangrid API must include your API key as a Bearer token in the Authorization header. Requests without a valid key return 401 Unauthorized and are not processed.

Obtaining your API key

Contact hello@vangrid.io to request API access. Once your account is provisioned, your API key is available in the Vangrid dashboard under Settings → API Keys.

Passing your API key

Include your key in the Authorization header on every request:

Authorization: Bearer your-api-key

curl -X POST https://api.vangrid.io/v1/spatial/query \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"aoi": {"type": "Point", "coordinates": [-122.4194, 37.7749]}}'

import requests

response = requests.post(
    "https://api.vangrid.io/v1/spatial/query",
    headers={"Authorization": "Bearer your-api-key"},
    json={"aoi": {"type": "Point", "coordinates": [-122.4194, 37.7749]}}
)

const response = await fetch("https://api.vangrid.io/v1/spatial/query", {
  method: "POST",
  headers: {
    "Authorization": "Bearer your-api-key",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    aoi: { type: "Point", coordinates: [-122.4194, 37.7749] }
  })
});

Authentication errors

HTTP status	Error code	Cause
`401`	`unauthorized`	Key is missing, malformed, or revoked
`403`	`region_not_authorized`	Key is valid but not authorized for the requested region

Example 401 response:

{
  "error": "unauthorized",
  "message": "Invalid or missing API key. Include your key as Authorization: Bearer <key>."
}

Best practices

Never hard-code your API key in source code or commit it to version control.

Store your key in an environment variable: VANGRID_API_KEY
Use separate keys for development and production environments
Rotate keys periodically via the dashboard
Revoke compromised keys immediately from Settings → API Keys

If you suspect a key has been exposed, revoke it in the dashboard and issue a new one before updating your application config.

Overview

API reference

Obtaining your API key

Passing your API key

Authentication errors

Best practices

​Obtaining your API key

​Passing your API key

​Authentication errors

​Best practices

Obtaining your API key

Passing your API key

Authentication errors

Best practices