Skip to content
Docs

    Authenticate with API keys

    5 min read · Updated View as Markdown

    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.

    Pick a credential

    To do thisUseCreated in your workspace underSent as
    Validate, plan and apply detection content from CIAPI key of the CI type (txk_…)Settings › Tokens & API (admins only)X-API-Key header
    Send alerts from Prometheus Alertmanager or your own scriptsAPI key of the ingest type (txk_…)Settings › Tokens & APIX-API-Key header
    Send traces, metrics and logs from OpenTelemetry SDKs and agentsIngest key (apm_…)Applications › APM & Traces › Setupx-tracix-ingest-key header
    Send browser or mobile real user monitoring dataRUM app keyApplications › Real User Monitoring › Setupx-tracix-app-key header
    Enroll a Tracix CollectorEnrollment tokenCollectors › Policies, on the policy's pageGiven 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.

    PermissionKey typeWhat it allows
    write:logsIngestLogs and external alert events. Give it to an Alertmanager or webhook key
    write:metricsIngestMetrics
    write:tracesIngestTraces
    security.readCIValidate and plan detection content, export a published package and download the detections CLI
    security.manageCIApply 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

    EndpointKeyPermission
    POST /api/security/detectionsCIsecurity.read to validate or plan, security.manage to apply
    GET /api/security/detections?job=<id>CIsecurity.read
    GET /api/security/detections/cliCIsecurity.read
    GET /api/security/detections/exportCIsecurity.read
    POST /api/ingest/alertmanagerIngestAny write: permission
    POST /api/ingest/eventsIngestAny write: permission

    Request and response details are in the workspace API reference. 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.

    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 CIUse a read key and an apply key in a pipelineWorkspace API referenceEvery endpoint that accepts an API keyAPI keys and ingest keysWho can create and revoke keys
    Report a problem with this page