API Keys

Where to find API keys

Go to Settings in the left sidebar, then select the API Keys tab. This page lists all keys associated with your account (or team, if you are in a team workspace).

Creating a key

1. Click New API Key.

2. Enter a descriptive name (e.g., laptop-dev, ci-pipeline, production).

3. Select the scopes this key needs:

   • read:sessions — timing, model, tokens, and cost. No content. Enough for a plugin to send events.
   • read:events — the above, plus which skills, subagents, tools, and commands ran, by name.
   • read:prompts — the above, plus prompt and response text.
   • read:full — the above, plus tool arguments, shell commands, file paths, and raw API bodies.

   Each level implies the ones below it. Scopes describe what Trenchcoat records, not what a request may do — every level can send events.

   • You can select both scopes on the same key.

4. Click Create.

The key is displayed once immediately after creation. Copy it now — it cannot be retrieved again. Trenchcoat only stores a hashed version of the key.

Key format

All Trenchcoat API keys start with the prefix ct_live_ followed by a random string:

ct_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

If you see a key that does not start with ct_live_, it is not a valid Trenchcoat key.

Keys table

The keys table shows all active keys for your workspace.

Revoking a key

To revoke a key:

1. Find the key in the table.
2. Click Revoke in the actions column.
3. Confirm in the dialog that appears.

Revocation is immediate. Any plugin or integration using that key will start receiving 401 Unauthorized responses. There is no way to un-revoke a key — if you revoke one by accident, create a new key and update your plugin configuration.

Using a key in the Trenchcoat plugin

Add the key to the env block of ~/.claude/settings.json:

{
  "env": {
    "TRENCHCOAT_API_KEY": "ct_live_your_key_here"
  }
}

Edit that file directly. The plugin never asks you to paste a key into a Claude Code conversation, because anything typed into a session becomes part of that session's transcript.

Then start a new Claude Code session — environment variables are read at session start — and run:

/trenchcoat:connect

This validates the key and configures telemetry export, including setting content-capture flags to match the key's scopes. Start one more new session so those settings take effect, then confirm with:

/trenchcoat:verify

If you rotate or revoke a key, update settings.json and re-run /trenchcoat:connect — it re-reads the key's scopes and adjusts what gets captured accordingly.

Using a key in direct API requests

Pass the key in the X-API-Key header on every request:

curl -X POST https://app.trenchcoat.io/api/v1/events \
  -H "X-API-Key: ct_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"events": [...]}'

The header name is case-insensitive, but X-API-Key is the conventional casing.

Security best practices

One key per environment. Use a separate key for your laptop, CI pipeline, and any production systems. This way, revoking a compromised key does not affect other environments.

Rotate keys quarterly. Create a replacement key, update your plugin or integration to use the new key, then revoke the old one. The "Last Used" column helps confirm the old key is no longer in use before you revoke it.

Never commit keys to git. Store keys in environment variables, a secrets manager, or a local config file that is listed in .gitignore. The plugin stores your key in a local config file outside your project directory by default.

Use the lowest capture level that answers your question. A key that only needs session timing and cost should be read:sessions. Widen it only when you actually want content stored — the server strips anything above the key's level before writing, so a narrow key is a real guarantee, not just a preference.