Skip to content

API keys

API keys are organization-scoped credentials for everything that talks to Hexcovery without a human signing in: the agent, CI/CD pipelines, automation scripts, and the public API. A key resolves to your organization, so any data sent or queried with it lands in — and stays inside — your organization.

API keys are managed by admins.

What you use a key for

  • The agent — the Hexcovery agent and OTLP clients authenticate with an organization-scoped key to ship metrics, logs, and traces. See Send your data.
  • CI/CD and automation — for example, posting a deploy annotation from a pipeline.
  • The public API — running OQL queries and managing annotations programmatically.

A key can reach the entire programmatic surface available to your organization (ingest, OQL queries, annotations, cron heartbeats) and nothing more — there is no raw-SQL access and no access to another organization's data.

Creating a key

  1. As an admin, open the organization's API keys management.
  2. Create a new key and give it a recognizable name (for example, prod-agent or ci-deploy).
  3. Copy the key when it is shown. Treat it like a password and store it somewhere safe (a secret manager or your CI's secret store). Do not commit it to source control.

Using a key

Pass the key in the X-API-Key header on every request:

# Run an OQL query
curl -s https://server/api/v1/dsl \
  -H "X-API-Key: $HEXCOVERY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "SELECT avg(cpu_usage_pct) FROM host LAST 1h"}'

# Post a deploy annotation from CI/CD
curl -s -X POST https://server/api/v1/annotations \
  -H "X-API-Key: $HEXCOVERY_API_KEY" \
  -d '{"name":"deploy/myapp","title":"v2.3.1 to production"}'

X-API-Key, not Bearer

Programmatic access uses the X-API-Key header. The Authorization: Bearer … slot is reserved for dashboard user sessions (JWTs) — passing an API key there is rejected. For the full breakdown of the two authentication methods, see Authentication.

Rotating and revoking

  • Rotate a key by creating a new one, updating wherever the old key is configured, and then revoking the old one once nothing depends on it.
  • Revoke a key the moment it is no longer needed or may have leaked. Revoking takes effect immediately — any client still using the revoked key stops being able to send or query data.

One key per purpose

Give each agent, pipeline, and integration its own key. That way you can rotate or revoke one without disrupting the others, and the audit log and usage stay easy to reason about.