Ingestion Keys

Secure, write‑focused credentials for streaming data into groundcover

Ingestion Keys let sensors, integrations and browsers send observability data to your groundcover backend. They are the counterpart of API Keys, which are optimized for reading data or automating dashboards and monitors.

---

Key types

Sensor*	Install the eBPF sensor on Kubernetes or Hosts/VMs
RUM	Send Real‑User‑Monitoring events using JS snippet embedded in web pages
Third Party	Integrate 3rd-party data sources that push data (e.g. OpenTelemtry, AWS Firehose, FluentBit, etc.)

*Only the Sensor has limited read capability in order to support pulling remote configuration such as OTTL parsing rules applied from the UI. RUM and Third Party have write-only configurations.

---

Creating an Ingestion Key

It is recommended to create a dedicated Ingestion Key for every data source, so that they can be managed and rotated appropriately, minimize exposure or risk, and allow groundcover to identify the datasource of all the ingested data.

1. Open Settings → Access → Ingestion Keys and click Create key.

2. Give the key a clear, descriptive Name (for example k8s-prod‑eu‑central‑1).

3. Select the Type that matches your integration.

4. Click Click & Copy Key.

   1. Unlike API Keys, Ingestion Keys stay visible on the page. Treat every reveal as sensitive and follow the same secret‑handling practices.

5. Store they Key securely, and continue to integrate your data source.

---

Using an Ingestion Key

Kubernetes sensor example

helm upgrade --install groundcover groundcover/groundcover \
  --set global.groundcover_token=<INGESTION_KEY>,clusterId={cluster-name}

OpenTelemetry integration (OTel/HTTP) example

exporters:
  otlphttp/groundcover:
    endpoint: http://{GROUNDCOVER_MANAGED_OPENTELEMETRY_ENDPOINT}:443
    headers: 
      apikey: {INGESTION_KEY}

pipelines:
  traces:
    exporters:
    - otlphttp/groundcover

---

Viewing keys

The Ingestion Keys table lets you:

• Reveal the key at any time.

• See who created the key and when.

• Sort by Type or Creator to locate specific credentials quickly.

---

Revoking a key

Click ⋮ → Revoke next to the key. Revocation permanently deletes the key, unlike API Keys which only disables it:

• The key will disappear from the list.

• Any service using it will receive 403 / PERMISSION_DENIED and will not be able to continue to send data or pull latest configurations.

This operation cannot be undone — create a new key and update your deployments if you need access again.

---

Ingestion Keys vs. API Keys

	Ingestion Key	API Key
Primary purpose	Write data (ingest)	Read data / manage resources via REST
Permissions capabilities	Write‑only + optional remote‑config read	Mirrors service‑account RBAC
Visibility after creation	Always revealable	Shown once only
Typical lifetime	Tied to integration lifecycle	Rotated for CI/CD automations
Revocation effect	Data stops flowing immediately	API calls fail

---

Best Practices

• One key per integration – simplifies rotation and blast radius.

• Store securely – AWS Secrets Manager, GCP Secret Manager, HashiCorp Vault, Kubernetes Secrets.

• Rotate regularly – create a new key, roll it out, then revoke the old one.

• Monitor for 403 errors – a spike usually means a revoked or expired key.

---