API key setup and authentication for TracePilot AI

Learn how to get your TracePilot API key, pass it to the SDK, understand the key format, and configure a custom endpoint for self-hosted deployments.

TracePilot AI authenticates your SDK via an API key you pass to the TracePilot constructor. This page explains how to get that key, how to use it safely, and what options are available if you’re running a self-hosted TracePilot instance.

Get your API key

Sign in at tracepilotai.com using GitHub or Google. After signing in, navigate to your account settings to find your API key.

All TracePilot API keys follow this format:

tp_live_xxxxxxxxxxxxxxxx

The tp_live_ prefix identifies it as a live production key. Copy the full key including the prefix.

Pass the key to the SDK

Pass your API key as the first argument to the TracePilot constructor:

import { TracePilot } from 'tracepilot-sdk';

const tp = new TracePilot('tp_live_YOUR_KEY');

That’s all you need for the default cloud setup. The SDK will authenticate all trace submissions using this key.

Never hardcode your API key directly in source code you commit to version control. Anyone with your key can submit traces on your behalf and consume your quota. Store it in an environment variable instead:

const tp = new TracePilot(process.env.TRACEPILOT_API_KEY!);

In a .env file (excluded from git):

TRACEPILOT_API_KEY=tp_live_xxxxxxxxxxxxxxxx

Custom endpoint (self-hosted)

If you’re running a self-hosted TracePilot ingest server, pass your server’s URL as the second argument to the constructor:

const tp = new TracePilot(
  'tp_live_YOUR_KEY',
  'https://your-server.com/api/ingest'
);

The custom endpoint must be a fully-qualified HTTPS URL pointing to a compatible TracePilot ingest API. The SDK sends all trace data to this URL instead of the default cloud endpoint.

The endpoint parameter is optional. Omit it entirely if you’re using TracePilot’s managed cloud service — the SDK defaults to the correct ingest URL automatically.

If your key is invalid

If your API key is missing, malformed, or revoked, TracePilot will fail to authenticate when submitting traces. To diagnose:

1. Confirm the key starts with tp_live_ — keys with any other prefix or format won’t be accepted
2. Check that you’re reading the key from the correct environment variable
3. Regenerate the key in your dashboard at tracepilotai.com/dashboard if it may have been compromised
4. Ensure no extra whitespace was copied into the key value

Authentication errors surface as SDK exceptions at trace submission time, not at construction time. If tp.startTrace() or tp.wrapOpenAI() throw an authentication error, the issue is with the key passed to the constructor.