Claim a workspace

On this page

An agent can set Track up with no person: signup needs no account, email or card. The person it works for takes the workspace over later with the claim link.

  • Who can make one: only a workspace key with the write scope, the key signup returns. A link hands over the whole workspace, so a read-only key or a key made for one project never gets one, from any route.
  • The link: claim_url from signup, https://alg.katrinalaszlo.com/claim/<token>. The install check, run with the workspace key, prints a fresh one as its last line, and ?format=env signup writes one as a comment after the key (# Claim this workspace: <url> (link valid until 2026-10-31 05:48 UTC)). Run with another key, the install check's last line says which key makes the link. Each link made is in the agent log as "Made a claim link", with what made it and when it stops working, never the link itself. The person opens it, signs in or creates an account, sees the workspace (its name, when and by what it was made, its projects, its events so far and what the agent did) and chooses "Add to my account". Track then opens the agent log, which starts with everything the agent did.
  • The window: a link works for 7 days, or until it is used. After that the workspace and its key keep working exactly as before; only the link stops. Nothing is deleted.
  • Re-issuing: POST /v1/claim-link with the workspace key (write scope) answers 201 with a new claim_url, claim_expires_at and claim. Earlier links keep working until they expire. A project key cannot make one (403 project_key), nor can a key without write (403 insufficient_scope); their next_step names the workspace key from signup, and if that key is lost, start a new workspace: only whoever holds it can hand this one over.
  • Checking: GET /v1/claim (any key of the workspace) answers claimed, claimed_at, status (claimed, unclaimed or unclaimed_link_expired), claim_expires_at of the newest unused link, live_claim_links (unused links that still work), key_changes_on_claim (false), can_make_claim_links (whether this key can make one), how_to_reissue and next_step. It never makes a link. claim_url is always null there: Track keeps only a hash of each link, so it cannot show one again. After the person says they claimed it, call GET /v1/claim, see claimed: true, and carry on.
  • What the person gets: every project in the workspace, the events stored so far, the agent log and the keys. They can make, rotate and revoke keys under Settings. A person who already has a workspace gets this one beside it and switches between them under Workspaces in the project menu.
  • Credentials: the key does not change on a claim. It keeps working, with the same scopes, until someone rotates or revokes it.
  • Cost and limits: free during the pilot, no card. Raw events are kept 14 days, a workspace holds up to 25 projects, and the request limits in section 9 apply, claimed or not.
  • Left unclaimed: nothing is deleted. The workspace keeps working with the key, and only someone holding the workspace key can see it, by signing in at /login with that key. A project key cannot sign in.
  • One owner: once claimed, another person's link answers "Already claimed", and POST /v1/claim-link answers 409 already_claimed: there is nothing to claim, so carry on with the key.

Three things that can look alike, and which Track needs:

  • Claiming is a person taking ownership of what an agent made. Track needs it only for the workspace to show up in a person's account; the agent's key works without it.
  • Approving is a person allowing a key for a terminal (alg connect, "Connect from a terminal" below). Track needs it only when a CLI asks for a key that way.
  • Inbox verification (a code or link sent to an email address) proves someone reads that inbox. Track has none and needs none: signup takes no email, and the claim link is shown to the agent, which hands it to the person.

You do not need to ask us to create a project. For a second one, use the "New project" button in the dashboard, POST /v1/projects, or the "New project" option when you connect a terminal. A workspace holds up to 25 projects. GET /v1/projects (read scope) lists them with their project_id; a key made for one project sees only its own.