API Keys

What an API key is for

A brand API key is a single bearer token that authenticates server-to-server calls on behalf of one brand. Trcker uses it for three things:

1. Public API (/api/public/*) — programmatic access to clicks, conversions, partners, and offers. Same scope as a brand operator session, but without a session cookie.
2. MCP server (/api/mcp) — lets AI assistants like Claude, ChatGPT, and Cursor read your program data. See the MCP server doc.
3. Click-capture script (/api/clicks/capture) — used by the JavaScript snippet on your site to record first-party clicks when a tracking link lands.

Each brand gets one key. Different keys for different brands; the same key never crosses brand boundaries.

Generating a key

1. Open Settings on the brand you want a key for.
2. Scroll to Brand API Key.
3. Click Generate API key.

The key is shown once in plaintext at the moment of generation. Copy it into your secret manager (1Password, AWS Secrets Manager, GitHub Actions secrets, etc.) immediately — Trcker never displays it again. We store a one-way hash on our side so we can validate incoming requests without ever being able to recover the original value.

The format is a 40-character random string prefixed with tk_. Example shape: tk_2a4f8c….

Using a key

Pass the key in the Authorization header as a bearer token:

`bash curl https://trcker.io/api/public/conversions \ -H "Authorization: Bearer tk_your_key_here" `

The MCP server accepts the same key via the standard Authorization: Bearer header — just point your AI client at https://trcker.io/api/mcp and configure the bearer.

The click-capture script can also accept the key via an x-api-key header for environments where setting Authorization is awkward (some CDNs strip it). Either header works.

Rotating

When you suspect a key has leaked or you want to roll it on a schedule:

1. Generate a new key from Settings (the page lets you create a replacement without invalidating the current one yet).
2. Update every consumer (your CI secrets, the MCP server config, the capture script) to use the new key.
3. Once you're sure nothing is using the old key, click Revoke on it.

There's no "rotate now" button that does this atomically — and that's deliberate. A blind atomic rotate would break every running consumer the moment it fires. Two-step rotation lets you migrate first, then revoke.

Scope

A brand key is scoped to its brand:

• ✅ Read/write on the brand's own clicks, conversions, partners, offers, postback logs, fraud signals, pricing rules.
• ❌ Cannot see other brands' data, even if you're the master admin.
• ❌ Cannot manage users, billing, or anything outside the brand boundary.

If you need cross-brand access (e.g. an agency running multiple brands), use the master account with the WorkOS session — there's no "master API key" today.

Revoking + leaks

If you think a key has leaked, revoke it immediately from Settings and generate a new one. Trcker logs every API request with the (hashed) key fingerprint, so you can audit usage after the fact via the Activity → Delivery log tab — filter to "API" entries.

Sample logs include source IP and user-agent, so you can usually narrow down which consumer was leaking. Reach out at hello@trcker.io if you need help reading the logs.