# Ingestion Keys

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](https://docs.groundcover.com/fleet-manager#remote-configuration) such as [OTTL parsing rules](https://github.com/groundcover-com/docs/blob/main/use-groundcover/broken-reference/README.md) 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: https://{GROUNDCOVER_MANAGED_OPENTELEMETRY_ENDPOINT}
    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.

***