Get started
Authentication
Personal keys, workspace keys and OAuth tokens: which one to use, and how each picks a workspace.
Every request carries one credential as a bearer token:
Authorization: Bearer <key or token>The CLI, the REST API and the MCP server accept the same three kinds.
| Personal key | Workspace key | OAuth token | |
|---|---|---|---|
| Belongs to | You | The workspace | You, through an MCP client |
| Reaches | Every workspace you're in | That workspace only | Every workspace you're in |
| Made by | tracee login, or Settings → Personal keys | Settings → Workspace keys | The client's sign-in (Claude, ChatGPT, Cursor…) |
| When someone leaves | Stops working in workspaces they left | Keeps working | Stops working in workspaces they left |
| Personal memories | Yes | No (team memories only) | Yes |
| Best for | Your own CLI and scripts | Servers, CI, automations | AI assistants |
Personal keys
tracee login opens Tracee in your browser. When you press Allow, the CLI receives a personal key named Tracee CLI · <your computer>. Under the hood this is a one-time code bound to a PKCE challenge the CLI made, so only the terminal that asked can use it, once, within five minutes.
You can also create personal keys yourself under Settings → Personal keys, and turn any of them off there. tracee logout turns off the key the browser login made.
Workspace keys
Create one under Settings → Workspace keys and name it after what will use it ("Nightly report", "GitHub Actions"). It acts only in that workspace and keeps working when the person who made it leaves, which is what you want for anything that runs unattended.
tracee login --key "$TRACEE_API_KEY" # or set TRACEE_API_KEY and skip loginOAuth tokens
MCP clients sign people in with OAuth 2.1 (dynamic client registration and PKCE), through https://traceeai.com/.well-known/oauth-authorization-server. The access token they get also works on the REST API. See MCP.
Choosing the workspace
A workspace key needs nothing more. A personal key or OAuth token that reaches several workspaces uses, in order:
- The
Tracee-Workspace: <workspace id>header, for one request (--workspace <id>in the CLI). - The workspace you selected for this credential with
POST /workspaces/{workspace_id}/select(tracee workspaces select <id>). It's remembered. - The only workspace you're in.
Otherwise the API answers 400 workspace_required and lists your workspaces. GET /me shows which workspace a credential acts on.
Who you appear as
Calls act as an agent named after the credential, for example API · Tracee CLI · laptop · dana@acme.com or API · GitHub Actions. That name appears in the audit log, on approval requests and in each post's history. See Guardrails and approvals.