> ## 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.

# Authenticate Requests to the Vangrid API

> Secure every Vangrid API request using your API key as a Bearer token. Learn how to obtain credentials, pass them correctly, and handle auth errors.

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.

<Note>
  All endpoint URLs, request examples, and sample responses on this page are illustrative. The Vangrid API is not yet publicly available — [contact us](mailto:hello@vangrid.io) to join early access.
</Note>

## Get an API key

Vangrid API access requires an enterprise account. To request one, email [hello@vangrid.io](mailto: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.

<Note>
  If you need multiple keys — for example, to isolate production from development environments — you can create additional keys from the dashboard at any time.
</Note>

## Pass your API key in requests

Include your API key in the `Authorization` header of every HTTP request, using the `Bearer` scheme:

```bash theme={null}
Authorization: Bearer <your-api-key>
```

Here are examples in common languages:

<CodeGroup>
  ```bash curl theme={null}
  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] } }'
  ```

  ```python python theme={null}
  import os
  import requests

  response = requests.post(
      "https://api.vangrid.io/v1/spatial/query",
      headers={
          "Authorization": f"Bearer {os.environ['VANGRID_API_KEY']}",
          "Content-Type": "application/json",
      },
      json={
          "aoi": {"type": "Point", "coordinates": [-122.4194, 37.7749]}
      },
  )
  ```

  ```javascript javascript theme={null}
  const response = await fetch("https://api.vangrid.io/v1/spatial/query", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.VANGRID_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      aoi: { type: "Point", coordinates: [-122.4194, 37.7749] },
    }),
  });
  ```
</CodeGroup>

## 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.

```json theme={null}
{
  "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.

```json theme={null}
{
  "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](mailto:hello@vangrid.io) to review your account permissions.

## Best practices

<Warning>
  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.
</Warning>

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.

<Tip>
  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.
</Tip>