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

# Vangrid API Authentication: Keys and Bearer Tokens

> All Vangrid API requests require a Bearer token. Learn how to obtain your API key, include it in requests, and handle authentication errors.

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](mailto: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
```

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

  ```python Python theme={null}
  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]}}
  )
  ```

  ```javascript JavaScript theme={null}
  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] }
    })
  });
  ```
</CodeGroup>

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

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

## Best practices

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

* 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**

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