API keys

API keys

API keys authenticate your backend + the MCP server to TrackLayer. Each key is scoped, revocable, and hashed at rest. We never see the full value after create.

That design matters for 2 reasons. First, you can issue narrowly scoped credentials instead of sharing one all-powerful secret across every service. Second, if a key is exposed, you can revoke just that key without rotating unrelated systems.

In practice, most teams should create separate keys for production, staging, and local development. Do not reuse one production key across every app, cron, worker, and integration. Smaller blast radius makes incidents much easier to contain.

Creating a key

1. Go to /settings > API Keys and click Create key.
2. Name the key. We recommend patterns like prod-api-<service-name> or staging-api-<service>.
3. Pick the minimum scopes the service actually needs:
   • events:write — send events
   • events:read — query events
   • platforms:read — list platform status
   • admin — settings, webhooks, team. Do not use this for the SDK.
4. Copy the key immediately. We show it once. After that, you only see the prefix, such as tl_live_XXXXXX, not the full value.

Store the full key in your environment variables or secret manager right away. Good options include Cloudflare Secrets, Vercel environment variables, AWS Secrets Manager, Doppler, 1Password Secrets Automation, or Vault. The important part is that the value lives in server-side secret storage, not in source control or client code.

If you are setting up a backend SDK, events:write is usually enough. If you are building internal tooling that reads delivery status or platform health, add the read scopes it needs. Only grant admin to trusted internal services that actually manage TrackLayer configuration.

Rotating

Rotate keys without downtime in this order:

1. Create a new key with the same scopes as the old one.
2. Deploy your backend or MCP server with the new key.
3. Revoke the old key.
4. Verify the change in the audit log.

Do not revoke first unless you are responding to an exposure incident. For planned rotation, overlap the new and old keys long enough to confirm traffic is still flowing. That avoids an unnecessary ingest outage caused by one stale environment, worker, or scheduled job still using the old value.

After rotation, check that new events continue arriving and that no service is still returning authentication failures. The audit log is useful here because it gives you a timestamped record of key creation and revoke activity tied to the account.

Revoking

To revoke a key, click Revoke in the key row.

Any delivery or API request using that key starts returning 401 immediately. Revocation is final. If you still need access, create a new key rather than expecting the old one to be recoverable.

Revoke as soon as a key is no longer needed. Dormant credentials are risk with no upside.

Scopes explained

| Scope           | Grants                                           |
|----------------|--------------------------------------------------|
| events:write   | POST /v1/ingest                                  |
| events:read    | GET /v1/events, /v1/deliveries                   |
| platforms:read | GET /v1/platforms                                |
| admin          | Everything except billing (which requires owner) |

Think of scopes as capability flags, not role labels. A service that only sends events should not be able to read event history or update webhooks. That separation is what lets you issue keys to multiple systems without trusting each one with your full account surface.

If you are unsure which scope to choose, start smaller. It is easier to create a second key with broader access later than to clean up after an over-scoped production secret leaked into logs, screenshots, or a CI variable dump.

Security

• Never commit keys to git. Use environment variables or a secret manager.
• Rotate production keys every 90 days.
• Use different keys per environment, especially staging vs production.
• If a key is exposed, revoke it immediately, create a replacement, and redeploy every service that used it.

Also avoid pasting keys into support tickets, chat threads, or screenshots. If you need help debugging auth, the visible prefix is usually enough for support to identify which key you mean.

See /docs/mcp-server for how API keys + plan tier interact with MCP rate limits.