# Headless Agent Access — Design (Parking Lot)

**Date: July 19, 2026** · Not implemented yet — this is the design for how AI agents (Claude Code / "Apex agents") could use Trackmint's backend directly, without the mobile/web UI, so autonomous agents can manage their own work the same way a human teammate does. Filed as requested: thought through now, built when prioritized.

**Theme this supports:** *"Built with AI. Works with AI and humans."* — the same workspace, board, and billing model should work whether the thing moving a card to "Done" is a person or an agent.

---

## 1. What "headless" needs to mean here

Today, Trackmint's only client is the Expo app talking to Firebase Auth + Firestore directly. An agent has no email/password to sign in with and shouldn't be issued one — agents need a credential type that is: scoped to one workspace, revocable without touching the human admin's login, and safe to hand to a script or CI job.

## 2. Proposed shape: workspace API tokens

```mermaid
flowchart LR
    Admin["Admin (Setup → Team → API Access)"] -->|"Generate token"| Token["Workspace API token<br/>tm_live_xxx…"]
    Token --> Agent["Claude Code / Apex agent"]
    Agent -->|"Authorization: Bearer tm_live_xxx…"| API["Trackmint API layer<br/>(new — thin REST/HTTPS Cloud Function)"]
    API -->|"validated, scoped to one workspace uid"| FS["Firestore workspaces/{uid}"]
```

- **Token, not password.** A long random token (`tm_live_...`), generated from Setup → Team → API Access by an Admin, mapped server-side to exactly one `workspace uid`. No agent ever sees a Firebase email/password.
- **Members roster gets an `agent` flag.** Reuse the existing `Member` shape — an agent is just another roster entry (`role: 'member'` or a new `'agent'` role) with `isAgent: true`, so it can be `assigneeId` on a task exactly like a human, and shows up in the same team list, capped to what a Worker can see (no billing) unless explicitly granted Manager-level token scope.
- **Revocable independent of login.** Deleting the token immediately cuts access without touching the admin's own account — important since these tokens will live in scripts/CI config.

## 3. Why not just reuse Firebase Auth custom tokens directly

Firebase Admin SDK could mint custom auth tokens per agent, which would work technically, but it: requires standing up Firebase Admin credentials somewhere agents can call (a bigger, riskier surface than a scoped REST token), gives the agent the *same* Firestore read/write rules as a human account (all-or-nothing on the whole `workspaces/{uid}` doc, not "board only" or "no billing"), and is harder to revoke selectively (you'd be managing individual Firebase users for agents). A thin API layer in front of Firestore is more work up front but is the only way to get per-scope permissions (e.g., "this agent can move cards and log time, but never touch invoices").

## 4. Minimal endpoint set (v1 sketch)

| Endpoint | What it does | Mirrors |
|---|---|---|
| `GET /v1/board` | List tasks, columns, and roster | BoardScreen |
| `POST /v1/tasks` | Create a task (title, type, client, estimate, assignee) | NewItemModal → addItem |
| `POST /v1/tasks/{id}/move` | Move to a column index | moveItem |
| `POST /v1/tasks/{id}/accept` | Accept a pending assignment | acceptAssignment |
| `POST /v1/tasks/{id}/start` | Accept + move to In Progress | startAssignment |
| `POST /v1/tasks/{id}/log-time` | Log hours (no live timer over HTTP — agents log after the fact) | addManualHours |
| `GET /v1/tasks/{id}` | Task detail | ItemDetailScreen |

Scoped explicitly to the assign/accept/start + time-logging surface first, since that's the concrete "let my agents use the app to manage their projects" ask — billing/invoice endpoints come later, gated to Manager/Admin-scoped tokens only.

## 5. Sequencing — what has to exist first

1. Multi-login-per-workspace (doc 23 §6) should land before this is fully useful for *human* teammates — but it is NOT a blocker for agent tokens, since a token is workspace-scoped, not user-scoped, from day one.
2. A thin Cloud Functions (or similar) HTTPS layer in front of Firestore, since the Expo app currently talks to Firestore directly with no backend — this is the actual new infrastructure piece.
3. Token issuance UI in Setup → Team.
4. Rate limiting / audit log on the new endpoints (who — which token — did what, when) before opening this beyond internal dogfooding.

## 6. Immediate, low-effort step toward dogfooding today

Until the API layer exists, Barry's Apex agents can already use Trackmint the same way a human does: add each agent as a `member` in Setup → Team (e.g. "Apex-Research-Agent", role Worker), and have a human relay task creation/status updates on their behalf, or drive the web build via browser automation the same way this session drove Firebase/App Store Connect. That's a real, working (if manual-bridge) form of "agents use the app" available right now, while the token/API layer above is scheduled.

## 7. v1 decision (July 2026) — direct Firestore access instead of the token API

The Cloud Functions layer in §5.2 requires Firebase's **Blaze plan** (Functions don't deploy on the free Spark plan at all, regardless of usage). Rather than gate agent access on a billing upgrade, v1 takes a different path:

**Agents talk to Firestore directly.** Concretely:

1. A **dedicated Firebase Auth account** (e.g. `agents@trackmint.app`) is created for agent use — never shared with a human login.
2. **Firestore security rules** allow that account (and any workspace the owner explicitly shares) to read/write the workspace document.
3. Each agent runs a small **local script / MCP server** (Node, using the Firebase Web SDK signed in as the agent account) wherever the agent already lives — Barry's Mac, a VPS, a Claude Code session. There is **no hosted server and no Blaze requirement**.

What this trades away versus the token API: (a) the app saves the workspace as one whole document, so a human saving from the app and an agent writing at the same moment can overwrite each other — agents should re-read immediately before writing and keep writes small/quick; (b) field-level restrictions (like hiding billing from a Worker-scoped token) can't be enforced per-field by Firestore rules on a single document — the agent account sees the whole workspace. Both are acceptable for a trusted-own-agents v1 and both are solved properly by the §4 API when it lands on Blaze.

Humans are unaffected: people keep using the iOS app / web app as normal. This path exists because agents have no fingers — the app UI is the human interface, direct data access is the agent interface.