Authentication
Log in to Traces via GitHub OAuth or API keys for programmatic access.
Authentication methods
| Method | Use case | Token type |
|---|---|---|
| CLI device auth | Interactive CLI login | Device token |
| GitHub OAuth | Web app login | Session cookie |
| API key | CI/CD, scripts, headless environments | trk_ prefixed key |
CLI login
traces loginOpens your browser for GitHub OAuth. The CLI stores a device token locally.
For environments without a browser (SSH, remote machines):
traces login --no-browserPrints a URL you can open on any device.
Check status
traces whoamiLogout
traces logoutThis revokes the server session and clears local credentials.
API keys
API keys provide scoped, programmatic access without interactive login. They're designed for CI/CD pipelines, scripts, and headless environments.
Creating API keys
- Go to
traces.com/@your-namespace/settings/api-keys - Click Create API Key
- Choose scopes and copy the key (starts with
trk_)
Keys are only shown once at creation time.
Scopes
| Scope | Permissions |
|---|---|
traces:write | Create and update traces and messages |
traces:read | Read traces and messages |
namespace:read | Read namespace info and members |
Using API keys with the CLI
Pass the key directly:
traces share --cwd . --key trk_your_api_key_hereOr set it as an environment variable:
export TRACES_API_KEY=trk_your_api_key_here
traces share --cwd .Auth precedence
The CLI resolves authentication in this order:
--keyflag (explicit, always wins)- Stored login from
traces login TRACES_API_KEYenvironment variable
Key limits
- Maximum 25 active keys per namespace
- Keys are scoped to the namespace they were created in
- Keys can be revoked at any time from settings