Skip to main content
Every request to the TraceRoot API sends a credential as a bearer token:
The API accepts three kinds of credential. Which ones a route takes depends on what the route does, so check the table under Which routes accept which credential before you pick one.

​
Credentials

​
Project API key

Create a key in your project’s settings in TraceRoot Cloud or your self-hosted dashboard. The full key is shown once, when you create it, so store it somewhere safe. A key belongs to one project, so requests made with it need no project_id. If you send one anyway, it must match the key’s project, or the request fails with 400.

​
Session token and CLI access token

Both identify you rather than a project. Sign in with the CLI:
This runs a browser login and stores a session token in ~/.config/traceroot/credentials.json. You can send that session token as the bearer directly. The CLI itself sends a short-lived access token instead. To mint one, exchange the session token at the web app:
The response holds accessToken, valid for 10 minutes. Mint a new one when it expires.

​
Which routes accept which credential

​
Reads with a user credential need project_id

Except for the account reads above, a session token or access token is not tied to a project, so a project-scoped read made with one must name the project as a query parameter:
Without it, the request fails with 400 and project_id query parameter is required for user credentials. Call GET /projects to list the project IDs you can use.

​
Writes need a user login

Creating, editing and deleting resources acts on your account, so these routes reject API keys with 403 and this operation requires a user login; API keys are project-scoped. Send a session token or access token instead. For detector, dashboard, widget and alert writes, send project_id in the create or edit body, or in the query on delete. Project updates and deletes take the project from the {project_id} path parameter. A write made with an access token is also refused with 401 once you run traceroot logout, even before the token expires.

​
Ingest is API-key only

The SDKs send traces and evaluation results with a project API key. These routes do not accept a user credential.

​
Errors

​
Self-hosted

On a self-hosted deployment, replace https://app.traceroot.ai with your own URL: the backend for /api/v1/public/* routes (http://localhost:8000 by default), and the web app for /api/cli/token (http://localhost:3000 by default). In the playground on each endpoint page, choose the Self-hosted server and enter your backend URL.