API authentication
Use the credential intended for your integration.
| Use | Credential | Where to get it |
|---|---|---|
| Website tracking | Public tracking ID (pt_…) | Website installation guide |
| Send backend telemetry | Backend key (pti_…) | Backend → Connection setup → Install |
| Agent access over MCP | Sign-in (OAuth), or a scoped personal query token | Agent connection in the dashboard |
| Dashboard REST API | Signed-in session or short-lived JWT | Better Auth session token exchange |
Dashboard REST API
The dashboard signs in through Better Auth and exchanges its session at /api/auth/token for a JWT. It sends Authorization: Bearer <jwt> to /api/v1/ routes. JWTs expire after five minutes; the dashboard refreshes them automatically. Current resource permissions still apply.
Cookie authentication is supported from trusted dashboard origins. Cross-origin requests need the configured dashboard origin and credentials enabled. The REST API does not currently offer long-lived generic API keys or the previously documented pt_live_ tokens.
Backend ingestion
Store your backend key in the application's server secrets as PIPETRACE_API_KEY. The SDK sends it with telemetry. Native OTLP HTTP exporters use Authorization: Bearer <backend key> on /v1/traces, /v1/logs and /v1/metrics. This key selects a project and environment; it cannot read dashboard data.
See Backend basics for installation and supported instrumentation.
Agents and automation
Connect an MCP client to /mcp by signing in. Paste the MCP URL from Agent connection into your client (in Claude Code: claude mcp add --transport http pipetrace <url>). The client opens your browser, you choose the projects and permissions to allow, and you can disconnect the app from Agent connection at any time. A disconnect or narrower grant applies on the app's next request.
Clients that cannot sign in can use a scoped personal query token, created under Advanced in Agent connection. Neither credential is an ingestion key, and neither authenticates ordinary dashboard REST routes. Revoking a grant or membership also removes the corresponding access.
Keep credentials separate
- Only the public tracking ID belongs in website HTML.
- Keep backend and agent tokens in server or agent secret settings, never URLs or browser bundles.
- Create a replacement key when rotating credentials or separating deployments; install it before revoking the previous key.
- A 401 means authentication failed. A 403 means the authenticated request is not allowed.