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

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)

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.