Authentication
Data API requests use an API key in the x-api-key header. The /health and /health/* endpoints do not require a key.
curl --fail-with-body -sS \
-H "x-api-key: $CONSTELLATION_API_TOKEN" \
"https://api.constellation.space/topology?freshness_seconds=900"
Signing into the console gives you a session token, not an API key. /telemetry, /topology, and /predictions accept only x-api-key; a session token sent as Authorization: Bearer fails with 401 auth_failed.
Get a key
Fleet SDK integration is available on Pro and Enterprise. For a Pro account with integration access enabled:
- Open Settings → API → API tokens in the console.
- Name the token and select its required scopes.
- Choose Create API token and copy the secret when it is shown.
Enterprise credentials and endpoints are supplied during onboarding.
Scopes
| Scope | Grants |
|---|---|
topology:read | GET /topology and GET /topology/series |
predictions:read | GET /predictions |
telemetry:write | POST /telemetry |
A valid key without a required scope receives 403 insufficient_scope; the required field identifies the missing scope. Use only the scopes your integration needs.
Keys identify the caller and are issued for an environment. Use the matching endpoint. API authentication and scopes do not imply tenant isolation on shared plans; see Tenant isolation.
Failed-auth lockout
Stop on 401 auth_failed. On 403, check scopes, account access, and whether the account is enabled before retrying.
Repeated authentication failures can return 429 auth_lockout, including after the credential has been corrected. Stop the failing client, correct the credential, and wait the full server-provided delay before resuming. Lockout thresholds and traffic limits are documented together in Errors and limits.
Store and rotate keys
Keep keys in an environment variable such as CONSTELLATION_API_TOKEN or in a secrets manager. Do not commit them, log them, include them in URLs, or ship them in frontend code.
Use one key per integration. Revoke exposed or unused keys under Settings → API → API tokens. For managed Enterprise credentials, contact Constellation for rotation.
The fleet agent stores its key in /etc/constellation/agent.env with mode 0600; applications write to the local socket without handling that key.
Verify access
Run the connection smoke test. An authenticated 200 from /topology confirms that the request succeeded. An empty entities array means no matching telemetry was returned for the requested window.