> ## Documentation Index
> Fetch the complete documentation index at: https://docs.corepillar.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Tracing keys

> Create and revoke the tk_live_ and tk_test_ keys your agents use to send traces, and understand how they are stored.

"API keys for sending traces from the SDK. Raw values are shown only once at creation."

A tracing key authenticates your agent when it sends traces to AgentHub. Each key belongs to one project, and every trace sent with it lands in that project.

## Who can manage keys

The **Tracing keys** tab is shown only to super admins. Creating and revoking keys requires the `manage_org_settings` permission; actions without it fail with "You do not have permission to manage tracing keys." or "You do not have permission to revoke tracing keys."

If you are an org Owner or Admin, ask one of your platform's super admins to create keys for you. The **Create a tracing key** link on a project's Overview page leads to this tab.

## Key format

| Part | Example |
| - | - |
| Prefix | `tk_live_` or `tk_test_` |
| Secret | 48 lowercase hexadecimal characters |
| Full key | `tk_live_3f9a…` (56 characters in total) |

The prefix records the key's environment. **Live** and **Test** keys work the same way; the environment is a label that helps you keep production and test credentials apart. AgentHub rejects anything that does not match this format with "Invalid tracing key format."

## Creating a key

<Steps>
  <Step title="Choose the project">
    Pick it in **Project**. The list shows every project in the organization. With no projects you see "Create a project first, then return here to manage tracing keys."
  </Step>

  <Step title="Choose the environment">
    Pick **Live** or **Test** in **Environment**. This also filters the list below to keys of that environment.
  </Step>

  <Step title="Create it">
    Select **+ New live key** (or **+ New test key**). The **New tracing key** window opens with the full key and the warning "Copy this key now — you won't be able to see it again." Select **Copy key**, then **Dismiss**.
  </Step>
</Steps>

<Warning>
  The full key is shown only in that window. AgentHub stores a SHA-256 hash of the key and a short hint, never the key itself, so nobody can retrieve it later. If you lose it, create a new key and revoke the old one.
</Warning>

## The key list

Each active key for the chosen project and environment appears as a row:

| Item | Example |
| - | - |
| Masked key | `tk_live_3f9a1c2e…b7d4`: the prefix, the first 8 characters of the secret, an ellipsis, and the last 4 characters |
| Created | "Created `<date>`" |
| Status | **Active** |
| Action | **Revoke** |

Revoked keys are not listed.

If the selected environment has no keys, you see "No live keys for this project" (or test). When the other environment has some, the message tells you, for example "This project has 2 test keys. Switch Environment to test to see them." Otherwise it offers **Create a live key**.

The project's Overview page also shows the newest active key in this masked form.

## Revoking a key

Select **Revoke** on the key's row. An inline confirmation appears: "Revoke? Ingestion with this key stops immediately." Select **Revoke key** to confirm, or **Cancel**.

Requests that use a revoked key are rejected with `401` and "Invalid or revoked tracing key." Revoking cannot be undone; create a new key instead.

## The key created with each project

Every new project is created with one live key automatically, and that key appears in the list like any other. Its full value is never displayed anywhere, so in practice you cannot use it. Create your own key for each integration.

## Legacy project keys

Alongside the hashed keys on this tab, each project also has a single project-level key from AgentHub's original design: the same key that is generated when the project is created. AgentHub still accepts it. When a presented key does not match an active hashed key, AgentHub checks it against the project's legacy key before rejecting the request.

Legacy keys are not shown on this tab and cannot be rotated from it. Revoking the auto-created key in the list does not disable its legacy copy. Because its value is never displayed, this only matters if the value was obtained some other way. Use keys created on this tab for all new work.

## Using a key

Send the key with each ingest request in either header:

```text theme={null}
Authorization: Bearer tk_live_...
x-tracing-key: tk_live_...
```

See the [tracing quickstart](/agenthub/developers/tracing-quickstart) for a full request, and [Idempotency and retries](/agenthub/developers/idempotency-and-retries) for safe re-sending.

Treat tracing keys as secrets. Keep them in your agent's environment or secret manager, not in source code.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.