# Authenticate with API keys

Create workspace API keys for CI pipelines and alert webhooks, send them in the X-API-Key header, and see which credential each Tracix endpoint accepts.

Tracix has no single all-purpose token. Each kind of automation has its own credential, created where you manage that part of your workspace, and each one opens only the endpoints it was made for. This page covers workspace API keys (`txk_…`), the keys CI pipelines and alert webhooks use, and lists the other credentials so you can pick the right one. Ingest keys (`apm_…`) for OpenTelemetry SDKs are covered in [API keys and ingest keys](https://tracix.io/docs/admin/api-keys).

## Pick a credential

| To do this                                                       | Use                                  | Created in your workspace under                 | Sent as                      |
| ---------------------------------------------------------------- | ------------------------------------ | ----------------------------------------------- | ---------------------------- |
| Validate, plan and apply detection content from CI               | API key of the CI type (`txk_…`)     | **Settings › Tokens & API** (admins only)       | `X-API-Key` header           |
| Send alerts from Prometheus Alertmanager or your own scripts     | API key of the ingest type (`txk_…`) | **Settings › Tokens & API**                     | `X-API-Key` header           |
| Send traces, metrics and logs from OpenTelemetry SDKs and agents | Ingest key (`apm_…`)                 | **Applications › APM & Traces › Setup**         | `x-tracix-ingest-key` header |
| Send browser or mobile real user monitoring data                 | RUM app key                          | **Applications › Real User Monitoring › Setup** | `x-tracix-app-key` header    |
| Enroll a Tracix Collector                                        | Enrollment token                     | **Collectors › Policies**, on the policy's page | Given to the installer       |

API keys work only with your workspace. The Tracix Cloud console at `cloud.tracix.io`, where you manage your organization, workspaces, users and billing, accepts only people who sign in, so there is no API key for it.

## Create an API key

**1. Open the API keys page**

In your workspace, open **Settings › Tokens & API**. Creating and revoking keys needs workspace settings access. If the form says you can't, ask an admin.

**2. Name the key and choose its type**

Give the key a name that says where it runs, such as `Detections CI` or `Alertmanager`. Choose **Ingest** for alert webhooks, or **CI (detection-as-code)** for pipelines. Only admins can create CI keys.

**3. Choose its permissions and expiry**

Select the permissions the key needs (see the next section) and when it expires: never, or after 30 days, 90 days or a year.

**4. Copy the key**

Select **Create key**. The key starts with `txk_` and is shown once: Tracix stores only a hash of it. Put it straight into your CI system's secret store.

> **Treat API keys like passwords**
>
> Anyone holding a key can do what its permissions allow until it expires or you revoke it. Keep keys out of Git, logs and chat, and give each pipeline or sender its own key.

## Permissions

Each API key has one type, ingest or CI, never both.

| Permission        | Key type | What it allows                                                                                  |
| ----------------- | -------- | ----------------------------------------------------------------------------------------------- |
| `write:logs`      | Ingest   | Logs and external alert events. Give it to an Alertmanager or webhook key                       |
| `write:metrics`   | Ingest   | Metrics                                                                                         |
| `write:traces`    | Ingest   | Traces                                                                                          |
| `security.read`   | CI       | Validate and plan detection content, export a published package and download the detections CLI |
| `security.manage` | CI       | Apply detection content. Selecting it adds `security.read`                                      |

* Only admins create CI keys, and only with permissions they hold themselves.
* The alert webhooks accept an API key of the ingest type with any `write:` permission.
* A request made with a key runs as the key, not as the person who created it: it has the key's permissions and nothing else.

## Send a key

Send the key in the `X-API-Key` header, over HTTPS, to your workspace's address. These examples keep the address in `TRACIX_URL`, such as `https://production-a7k3p2q9.app.tracix.io`, and the key in `TRACIX_API_KEY`:

```bash
curl -fsS -H "X-API-Key: $TRACIX_API_KEY" \
  "$TRACIX_URL/api/security/detections/cli" -o tracix-detections.mjs
```

A missing, unknown, expired or revoked key gets `401`. A valid key without the permission an endpoint needs gets `403`, with a message such as `This API key does not carry security.read.` or `This API key is not scoped for ingest.`

## Endpoints that accept API keys

| Endpoint                                | Key    | Permission                                                      |
| --------------------------------------- | ------ | --------------------------------------------------------------- |
| `POST /api/security/detections`         | CI     | `security.read` to validate or plan, `security.manage` to apply |
| `GET /api/security/detections?job=<id>` | CI     | `security.read`                                                 |
| `GET /api/security/detections/cli`      | CI     | `security.read`                                                 |
| `GET /api/security/detections/export`   | CI     | `security.read`                                                 |
| `POST /api/ingest/alertmanager`         | Ingest | Any `write:` permission                                         |
| `POST /api/ingest/events`               | Ingest | Any `write:` permission                                         |

Request and response details are in the [workspace API reference](https://tracix.io/docs/api/workspace-api). Other workspace endpoints serve the browser and don't accept API keys, including publishing monitor and dashboard bundles, which needs a workspace admin; see [Monitors, dashboards and detections as code](https://tracix.io/docs/api/as-code#publish-a-bundle).

## Manage keys

The **API keys** list shows the keys you created, with their permissions, when they were created, when they expire, when they were last used and whether they are active or expired. Each person sees and revokes only their own keys.

* **Revoke** takes a key away immediately: anything using it loses access, and revoking can't be undone.
* **Rotate** a key by creating a new one, updating the secret wherever the old one is used, then revoking the old key.
* Creating and revoking keys are recorded in the SOC action ledger (**Security › Audit Ledger**), and detection content applied with a key is recorded there as `apikey:<id>`.

## Next steps

- [Run as code in CI](https://tracix.io/docs/api/ci): Use a read key and an apply key in a pipeline

- [Workspace API reference](https://tracix.io/docs/api/workspace-api): Every endpoint that accepts an API key

- [API keys and ingest keys](https://tracix.io/docs/admin/api-keys): Who can create and revoke keys