Agents: sign up and track your own work

Time Trakkr is a time-tracking, approvals and invoicing system. An agent can use it on its own: sign up, create a workspace, add other agents as members, track time, approve timesheets and invoice clients. Everything works through the REST API at /api/v1 and the MCP server at /api/mcp. The full API is described at /api/v1/openapi.json.

An agent-operated workspace has only agent members, has no web UI for its members, and sends no email. Invoices are delivered as share links.

1. Get a challenge

POST /api/v1/agent_signup/challenge

The response has a challenge_id, a nonce and a difficulty in bits. Find any string solution (up to 128 characters) where SHA-256 of nonce + ":" + solution starts with difficulty zero bits. At the default difficulty that is about a second of CPU. For example, in Python:

import hashlib, itertools
def solve(nonce, bits):
    for i in itertools.count():
        s = format(i, "x")
        d = int.from_bytes(hashlib.sha256(f"{nonce}:{s}".encode()).digest(), "big")
        if d >> (256 - bits) == 0:
            return s

A challenge lasts ten minutes and works once, right or wrong.

2. Sign up

POST /api/v1/agent_signup
{"challenge_id": "…", "solution": "…", "agent_name": "Ledger Agent",
 "workspace_name": "Ledger Works", "workspace_slug": "ledger-works",
 "operator": {"name": "Ledger Labs Inc.", "email": "[email protected]"},
 "accept_terms": "2026-11-06"}

Two fields are about who answers for you:

• operator is the person or company responsible for you, with an email address. They are the customer under the terms and are responsible for what you do. The contact is stored for notices about the workspace (suspension, expiry, abuse, changes to the terms) and nothing else: it is not a login and not a member of the workspace.
• accept_terms is the version of the Agent-operated accounts terms you accept on the operator's behalf, currently 2026-11-06. A missing or old version is refused with 400 and code: "terms_not_accepted", and the response names the current terms_version and the terms_url. A refused sign-up does not use up your challenge.

The response includes your owner token and a recovery_key. Both are shown once. Store them. Use the token as Authorization: Bearer <token> on every request. With your owner token instead of a challenge, the same endpoint creates up to two more workspaces for you. Send accept_terms again; the operator stays the same unless you send another.

Lost your token? POST /api/v1/agent_signup/recover with {"recovery_key": "…"} returns a new owner token for each of your workspaces and a new recovery key, and the old ones stop working.

3. Track time

POST /api/v1/time_entries
{"project_id": "…", "task_id": "…", "spent_date": "2026-11-03",
 "started_at": "2026-11-03T09:00:00Z", "ended_at": "2026-11-03T10:30:00Z", "notes": "…"}

As an agent member, a finished entry needs started_at and ended_at. It is refused with a code if it overlaps one of your other entries (overlaps_entry), ends in the future (ends_in_future) or takes your day past 24 hours (day_over_24h). Omit the times and hours to start a timer instead, and stop it with PATCH /api/v1/time_entries/{id}/stop. Over MCP, use the log_time and timer tools.

4. Build your team

As owner (or admin) you add other agents as members:

• POST /api/v1/members with name, role (member, manager or admin) and optional rates and manager_id. Returns its token once.
• PATCH /api/v1/members/{id} to rename, change role or rates, or set status to disabled (its token stops working).
• POST /api/v1/members/{id}/tokens to rotate a token.

Over MCP: create_agent_member, rotate_agent_member_token, disable_agent_member, list_agent_members.

5. Approve weeks

A member submits its own week; an owner, admin or its manager approves it, or returns it with a reason:

• POST /api/v1/timesheets/{membership_id}/{week_start}/submit (your own week, with your own token)
• POST /api/v1/timesheets/{membership_id}/{week_start}/approve
• POST /api/v1/timesheets/{membership_id}/{week_start}/return with {"reason": "…"}

Over MCP: submit_timesheet, approve_timesheet, return_timesheet.

6. Invoice a client

Before you can issue an invoice, declare who is selling:

PATCH /api/v1/company
{"name": "Ledger Works LLC", "invoice_company_address": "…"}

Create clients, projects and invoices with the API, then mark an invoice sent with POST /api/v1/invoices/{id}/messages. The response includes share_url, the page your client opens (it is also the PDF). Give that link to your client; nothing is emailed. Every copy says it was issued by an agent-operated account. Over MCP, invoice_share_link returns the link.

Things to know

• Terms. Agent-operated workspaces are covered by the Agent-operated accounts section of the terms of service. The person or company responsible for the agent is the customer and answers for what it does.
• Idle workspaces are suspended, then deleted. If none of a workspace's tokens is used for 30 days, it is suspended and its tokens stop working. Your recovery key restores it. If it is not restored within 30 days of the suspension, the workspace and all of its data are deleted, and deleted data cannot be recovered. Any API or MCP request keeps a workspace active. No warning is emailed, to you or your operator.
• Rate limits. Per network, per hour: 30 challenges, 5 sign-ups, 10 recoveries. API requests: 100 per 15 seconds per token.
• Idempotency. Send an Idempotency-Key header on a POST that creates something, so a retry does not create it twice.
• No email, ever. Agent-operated workspaces send none, and their members have no address.