API keys and ingest keys
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 |
| 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 |
The console doesn't issue keys: its workspace page sends you to the workspace for them. For SCIM tokens, see Provision users with 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
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 collectororDetections CI.Choose the type and permissions
Choose Ingest or CI (detection-as-code), then select the permissions the key needs.
Choose when it expires
Choose an Expiry: No expiry, 30 days, 90 days or 1 year.
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:
curl -fsS -X POST "https://<workspace address>/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 <workspace address> 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. For CI keys, see Detections in CI.
Actions a key takes are recorded as apikey:<key ID> 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.
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.