# API keys and ingest keys Create workspace API keys for collectors, webhook senders and CI with the permissions and expiry they need, and manage the ingest keys OpenTelemetry SDKs use. Machines authenticate to a workspace with keys you create in that workspace. This page covers **API keys**, which start with `txk_` and serve collectors, webhook senders and CI pipelines, and **ingest keys**, which start with `apm_` and authenticate data from OpenTelemetry SDKs. ## Which credential do you need? | To do this | Use | Create it in the workspace under | Send it as | | ------------------------------------------------------------- | ------------------------------------------------ | ----------------------------------------------- | ---------------------------------------------------------------------------------------------- | | Send traces, metrics and logs from an OpenTelemetry SDK | Ingest key (`apm_…`) | **Applications › APM & Traces › Setup** | The `x-tracix-ingest-key` header | | Send browser or mobile real user monitoring data | RUM app key, one per application and environment | **Applications › Real User Monitoring › Setup** | The `x-tracix-app-key` header; see [Browser RUM](https://tracix.io/docs/collect/instrument/browser-rum) | | Send alerts from Alertmanager or events from your own scripts | API key of the **Ingest** type (`txk_…`) | **Settings › Tokens & API** | The `X-API-Key` header | | Validate, plan and apply detection content from CI | API key of the **CI** type (`txk_…`) | **Settings › Tokens & API** | The `X-API-Key` header | | Install and enroll a Tracix Collector | Enrollment token | **Collectors › Policies** | The installer's `--token` option; see [Install the collector](https://tracix.io/docs/collect/collector/install) | The console doesn't issue keys: its workspace page sends you to the workspace for them. For SCIM tokens, see [Provision users with SCIM](https://tracix.io/docs/admin/scim). ## API keys API keys live in each workspace. Open **Settings** and select **Tokens & API** to reach the **API keys** page. Creating and revoking keys needs permission to manage workspace settings, which the workspace Admin role has. ### Key types and permissions Each key is one of two types, and carries only the permissions you choose when you create it: | Type | Permission | Shown as | What it allows | | ---------------------- | ----------------- | --------------- | ------------------------------------------------------------------------------ | | Ingest | `write:metrics` | Write metrics | Send metrics from collectors and scripts | | Ingest | `write:logs` | Write logs | Send logs and external alert events, from Alertmanager or `/api/ingest/events` | | Ingest | `write:traces` | Write traces | Send traces from collectors | | CI (detection-as-code) | `security.read` | Security read | Validate and plan detection content from CI | | CI (detection-as-code) | `security.manage` | Security manage | Apply detection content from CI. Includes `security.read` | The rules: * One key can't mix ingest and CI permissions. Create one key for collectors and another for CI. * Only workspace Admins can create CI keys, and only with permissions they hold themselves. * Ingest keys can't carry any other permission, because they're spread across many hosts. Today, API keys of the **Ingest** type are accepted by the Alertmanager webhook (`/api/ingest/alertmanager`) and the generic events endpoint (`/api/ingest/events`). OpenTelemetry SDKs authenticate with ingest keys (`apm_…`) instead, and collectors enroll with enrollment tokens. ### Create an API key **1. Name the key** Under **Create API key**, enter a **Name** of up to 100 characters that says where the key is used, such as `Production collector` or `Detections CI`. **2. Choose the type and permissions** Choose **Ingest** or **CI (detection-as-code)**, then select the permissions the key needs. **3. Choose when it expires** Choose an **Expiry**: **No expiry**, **30 days**, **90 days** or **1 year**. **4. Create and copy it** Select **Create key**. Copy the key from **New API key created** and store it in your secret manager: it won't be shown again. > **Keep keys out of source control** > > Store CI keys as pipeline secrets and keep them out of collector configurations. Anyone with a key can use its permissions until it expires or you revoke it. ### Use an API key Send the key in the `X-API-Key` header to your workspace's address. For example, to send an event to the generic events endpoint with an ingest key: ```bash curl -fsS -X POST "https:///api/ingest/events" \ -H "X-API-Key: $TRACIX_API_KEY" \ -H "Content-Type: application/json" \ -d '{"events":[{"dedupeKey":"disk-web-01","status":"firing","entity":"web-01","title":"Disk almost full"}]}' ``` Replace `` with your workspace's address, such as `production-a7k3p2q9.app.tracix.io`. Each event needs a `dedupeKey`, an `entity` and a `status` of `firing` or `resolved`; send up to 100 per request. Events open and resolve alerts that feed [problems and cases](https://tracix.io/docs/alerting/problems-and-cases). For CI keys, see [Detections in CI](https://tracix.io/docs/api/ci). Actions a key takes are recorded as `apikey:` rather than as a person. ### Review and revoke keys The **API keys** list shows each key's name and type, its permissions, when it was created, when it expires and when it was last used, and its status: `active` or `expired`. Revoked keys leave the list, and each person sees only their own keys. To revoke a key, select **Revoke** on its row and confirm **Revoke key**. Revoked keys stop working right away and can't be restored; create a new key to replace one. ## Ingest keys for OpenTelemetry SDKs Ingest keys authenticate OTLP data sent to the workspace's gateway, such as `https://otlp-http-a7k3p2q9.app.tracix.io`. The gateway checks the `x-tracix-ingest-key` header on every request and refuses requests without an active key. ### Create an ingest key In the workspace, open **Applications › APM & Traces**, select the **Setup** tab, and under **Ingest keys** select **New key**. Enter: | Field | What it's for | | ----------------- | -------------------------------------------------------------------------------------------- | | **Name** | Where the key is used, such as `checkout-api` | | **Environment** | The `deployment.environment.name` given to spans that don't set one. `production` by default | | **Service group** | Optional. The service group given to spans that don't name one | Select **Create key**. The key starts with `apm_` and is shown once, with **Copy key** beside it: save it now. Until you leave or reload the page, the **Setup** page fills it into its instructions; after that they show `YOUR_INGEST_KEY` for you to replace. See [Send your first trace](https://tracix.io/docs/get-started/quick-start). ### Manage ingest keys The **Ingest keys** list shows each key masked: like API keys, an ingest key can't be read again after it's created. Each key has buttons to: * **Pause** the key, which stops it authenticating, or **resume** it. * Change its **default service group**. Seeing the list, and creating, pausing and resuming ingest keys, needs the workspace Admin role (permission to manage APM). A new, paused or resumed key takes effect within about 30 seconds. Ingest keys can't be deleted; pause a key you no longer use, and rotate by creating a new key, moving your services to it, then pausing the old one. ## Next steps - [OTLP endpoint and ingest keys](https://tracix.io/docs/collect/instrument/otlp): Endpoints, protocols and headers for SDKs - [Authenticate with API keys](https://tracix.io/docs/api/authentication): Which credential each endpoint accepts - [Monitors, dashboards and detections as code](https://tracix.io/docs/api/as-code): Manage content from Git - [Collector policies](https://tracix.io/docs/collect/collector/policies): Enrollment tokens and fleet configuration