Docs navigation

API tokens

Personal access tokens (thub_pat) — how the CLI authenticates to TracesHub, scoping, expiry, and revocation.

The agent-trace CLI authenticates to TracesHub with a personal access token — a thub_pat_… string minted in the app and bound to a remote with agent-trace remote add … --token (or --token-env). Web sign-in is separate (GitHub OAuth); tokens exist purely for the CLI and CI.

Minting a token

Settings → API tokens → Mint token. You choose:

  • Name — free text, for telling tokens apart later (“laptop CLI”, “CI pipeline”).
  • Scope target:
    • User token — works across all of an org’s projects you can access. One user token per org covers all your repos there.
    • Project token — limited to a single project. The gateway physically refuses it anywhere else. Prefer this for CI and anything shared.
  • Scopes — by default the token carries both traces:read and traces:write (the maximum you have); optionally narrow it, e.g. a read-only token for a reporting job.
  • Expiry — 1 year by default; 30 days, 90 days, or 2 years selectable.

The secret is displayed once, at creation. Copy it immediately — TracesHub stores only a hash and can never show it again. If you lose it, revoke and mint a new one.

Tokens are capped by your access

A token never grants more than the minter’s own effective access, and the cap is enforced at use time: if your access to a project is later reduced or removed, every token you minted is reduced with it, automatically. Tokens delegate your access — they don’t create access.

Using a token

Paste it into the remote add command from your project’s Setup tab:

agent-trace remote add origin \
  "https://api.traceshub.com/at/<org>/<repo>" --token thub_pat_…

For CI or shared machines, prefer --token-env:

agent-trace remote add origin \
  "https://api.traceshub.com/at/<org>/<repo>" --token-env TRACESHUB_TOKEN

Only the variable name is persisted; the secret stays in your CI secret store. How the CLI stores and resolves tokens is documented in the CLI docs: push / pull / sync — Authentication.

Managing tokens

Settings → API tokens lists all your tokens with their scope (user or project, and which project), scopes, visible prefix, expiry, and last used time — never the secret.

  • Revoke immediately invalidates a token: any CLI or CI using it gets 401 on the next request. Revocation cannot be undone.
  • Expired tokens stop working on their own and stay listed for reference.
  • Use last used to find stale tokens worth revoking.

Good practice

  • One token per machine or pipeline, named accordingly — so revoking one place doesn’t break another.
  • Project-scoped tokens for CI; user tokens for your own laptop.
  • Shorter expiries for anything that leaves your laptop.
  • Treat a token like a password. If it may have leaked, revoke first, investigate second — minting a replacement takes seconds.