Authenticate API requests
Bearer API keys, scopes, and pinning the dated API contract.
Send an API key in the Authorization header and pin the contract version your application expects.
Send a bearer key
Pass the key as a bearer credential on every protected request:
Authorization: Bearer your_gridstate_api_key_hereCreate keys in the Gridstate console. The console displays each secret once.
Keep credentials out of URLs
Store keys in environment variables or a secret manager. Never put a key in a query parameter, committed configuration, log message, or support ticket.
Choose the required scope
Each key has one or more scopes:
| Scope | Grants access to |
|---|---|
commercial-core:read | Released queue, generation, operations, coverage, and provenance data |
sites:read and sites:write | Tenant-scoped site records |
assessments:read and assessments:write | Site assessments, comparisons, and exports |
data:read | Acquired evidence and change-monitoring tools outside the commercial core |
A valid key without the required scope receives 403 Forbidden.
Pin the API contract
Send the dated contract that your application supports:
Gridstate-Version: 2026-08-24An unsupported value returns 400 with the unsupported_api_version code. Combine version pinning with point-in-time parameters when you need reproducible historical reads.
Call public operational endpoints
These endpoints do not require a credential:
| Endpoint | Purpose |
|---|---|
/v1/health | Confirm that the API process is responding |
/v1/ready | Confirm that required dependencies are ready |
/v1/release | Inspect the active release metadata |
/v1/error-codes/{code} | Read remediation for a stable error code |
Every data, site, assessment, and Model Context Protocol (MCP) request requires authentication.