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 | 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
Use the /mcp interface with a personal query token. Choose its project grants and scopes in Agent connection. These tokens are separate from ingestion keys and do not authenticate 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.