# 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](/use-groundcover/fleet-manager.md#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.

***


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.groundcover.com/use-groundcover/remote-access-and-apis/ingestion-keys.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.