Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.vangrid.io/llms.txt

Use this file to discover all available pages before exploring further.

Every request to the Vangrid API must be authenticated with an API key passed as a Bearer token. This page covers how to obtain a key, how to include it in your requests, and how to handle common authentication errors.

​
Get an API key

Vangrid API access requires an enterprise account. To request one, email hello@vangrid.io with your name, organization, and a brief description of what you’re building. Once your account is provisioned, you can generate and manage API keys from the Vangrid dashboard. Each key is scoped to your account and carries the permissions assigned to your plan.
If you need multiple keys — for example, to isolate production from development environments — you can create additional keys from the dashboard at any time.

​
Pass your API key in requests

Include your API key in the Authorization header of every HTTP request, using the Bearer scheme: 
Authorization: Bearer <your-api-key>
Here are examples in common languages: 
curl -X POST https://api.vangrid.io/v1/spatial/query \
  -H "Authorization: Bearer $VANGRID_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "aoi": { "type": "Point", "coordinates": [-122.4194, 37.7749] } }'

​
Authentication errors

If something goes wrong with your credentials, the API returns one of two status codes:

​
401 Unauthorized

A 401 response means the API could not authenticate your request. Common causes:
  • The Authorization header is missing from the request.
  • The API key is malformed or contains extra whitespace.
  • The API key has been revoked or has expired.
{
  "error": "unauthorized",
  "message": "A valid API key is required. Include it as a Bearer token in the Authorization header."
}
Check that you’re reading the key from the correct environment variable and that the header is formatted exactly as Bearer <your-api-key> with a single space between Bearer and the key.

​
403 Forbidden

A 403 response means the API recognized your credentials but your account does not have permission to perform the requested action. Common causes:
  • The endpoint or feature is not included in your account tier.
  • Your API key is scoped to a different environment or region.
  • Your account has reached a usage limit.
{
  "error": "forbidden",
  "message": "Your account does not have access to this resource. Contact hello@vangrid.io to upgrade or adjust your permissions."
}
If you receive an unexpected 403, contact hello@vangrid.io to review your account permissions.

​
Best practices

Never hard-code API keys in your source code or commit them to version control. Anyone with access to your repository would be able to use your credentials.
Follow these practices to keep your credentials secure:
  • Use environment variables. Read your API key from an environment variable such as VANGRID_API_KEY rather than writing it directly in code. Use a .env file locally and a secrets manager in production.
  • Rotate keys regularly. Generate a new API key on a regular schedule and revoke old ones from the dashboard. Treat key rotation as routine maintenance, not just a response to incidents.
  • Use separate keys per environment. Create distinct keys for development, staging, and production. If a development key is compromised, your production workload is unaffected.
  • Revoke keys you no longer use. If a key was shared with a contractor, used in a demo, or belongs to a deprecated integration, revoke it promptly from the dashboard.
  • Monitor for unexpected usage. Review your API usage in the dashboard periodically. Unusual spikes in request volume may indicate a leaked key.
If you suspect a key has been compromised, revoke it immediately from the dashboard and generate a replacement. Then audit recent API activity for any unauthorized requests.