Skip to main content
Wrixton uses a simple per-user API key model. Every user has exactly one key — a random secret string that grants access to that user’s items and nothing else. There are no passwords, sessions, or OAuth flows: possessing the key is proof of identity, so keep it somewhere safe.

​
Obtaining your API key

API keys are generated by an instance administrator using the track user add command. When a user is created, the key is printed exactly once: 
created ryan  (309234af-1a2b-4c3d-8e9f-0a1b2c3d4e5f)
  api_key: a43e054c8f2d1b...

share api_key with the user. They configure with: track config
The api_key is printed only once at creation time and is never retrievable from the server afterward. Copy it immediately and store it in a password manager or other secure location. If you lose it, you will need to rotate it — which invalidates the old key and issues a new one.

​
Configuring the CLI

Run track config to store your key. It prompts for the key with a hidden input (nothing echoed to the terminal) and writes ~/.track/config.toml with file permissions 600: 
track config

Track api_key: ········
wrote /home/you/.track/config.toml
authenticated as ryan
The resulting config file looks like: 
api_key = "a43e054c8f2d1b..."
The api_url field is omitted when using the default shared deployment (https://projects.wrixton.xyz). After running track config, every CLI command reads the key from this file automatically. You can inspect the current config at any time: 
track config --show

​
Using an environment variable

If you prefer not to write a config file — for example in a CI environment or a shell script — set TRACK_API_KEY instead: 
export TRACK_API_KEY=a43e054c8f2d1b...
track today
The environment variable takes precedence over ~/.track/config.toml. You can similarly override the API endpoint with TRACK_API_URL (useful if you are running a local or self-hosted instance).
If neither the config file nor the environment variable is present, every CLI command exits immediately with: error: track is not configured. Run: track config

​
Passing the key in direct API requests

All HTTP endpoints require the key in the x-track-key request header: 
x-track-key: <your-api-key>
For example, to fetch today’s items directly from the API: 
curl https://projects.wrixton.xyz/api/today \
  -H "x-track-key: a43e054c8f2d1b..."
The CLI handles this header automatically; you only need to set it manually when building integrations or calling the API from your own code.

​
Authenticating in the web UI

When you open the web UI at projects.wrixton.xyz for the first time in a browser, you’ll be prompted to paste your API key. The UI stores it in localStorage, so the prompt only appears once per browser. To switch accounts or clear the stored key, use Settings in the web UI, or clear localStorage for the site manually through your browser’s developer tools.

​
Calendar feed authentication

The live calendar subscription feed passes the key as a key query parameter rather than a header (most calendar clients don’t support custom headers): 
https://projects.wrixton.xyz/api/calendar?key=<your-api-key>
Subscribe to this URL in any calendar app that supports Internet calendars (use webcal:// instead of https:// if your app requires it). The feed is read-only and scoped to your key exactly like the rest of the API. Append &all=1 to include done and canceled items.

​
Rotating a compromised key

If your key is leaked or you suspect unauthorized access, contact your instance administrator to rotate it immediately. Rotation is an admin-only operation that invalidates the old key and issues a new one. The administrator runs: 
track user rotate ryan

  ryan  (309234af-1a2b-4c3d-8e9f-0a1b2c3d4e5f)
  api_key: f91b3a7d2e...

the old key is now invalid. Reconfigure with: track config
The old key stops working immediately. Once you receive the new key, run track config to store it, and update any other places the old key was saved — browser localStorage, calendar subscriptions, scripts, and so on.
If you are the instance administrator, track user rotate requires the TRACK_SERVICE_KEY environment variable to be set. Treat this credential with care: never commit it to version control and unset it from your shell after use — unset TRACK_SERVICE_KEY.