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

# 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](https://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:

```typescript theme={null}
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.

<Warning>
  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:

  ```typescript theme={null}
  const tp = new TracePilot(process.env.TRACEPILOT_API_KEY!);
  ```

  In a `.env` file (excluded from git):

  ```bash theme={null}
  TRACEPILOT_API_KEY=tp_live_xxxxxxxxxxxxxxxx
  ```
</Warning>

## 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:

```typescript theme={null}
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.

<Tip>
  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.
</Tip>

## 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](https://tracepilotai.com/dashboard) if it may have been compromised
4. Ensure no extra whitespace was copied into the key value

<Note>
  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.
</Note>