Runn Token Broker

A middleware API that turns Runn's account-level API token into safe, per-user timesheet access.

1. The Problem

Runn's API v1 (https://api.runn.io) only issues account-level tokens, created by admins under Settings → API. A token is tied to the account, not to a user — so any write-scoped token can modify anyone's timesheets. There is no personal access token, and none is on Runn's public roadmap.

We still want individual users (starting with: us) to automate their own timesheet submission without ever holding the privileged token. The answer is a small token broker: a service that holds the one privileged Runn token server-side and issues its own scoped, per-user tokens on top.

2. Architecture

The broker is not a transparent proxy. It exposes its own small API (/my/…) and translates each call into a specific, constrained Runn API call. Clients cannot reach arbitrary Runn endpoints through it.

3. Request Flow

4. Broker API Surface

Keep it deliberately tiny. Every endpoint maps to one constrained upstream operation.

Broker endpoint	Upstream (Runn v1)	Constraint applied
POST /my/timesheet	POST /actuals/timeentry	personId forced from token; date range limited (e.g. current ± 1 period)
POST /my/timesheet/bulk	POST /actuals/bulk/	All entries rewritten to caller's personId; ≤ 100 entries; broker paces same-day entries
GET /my/actuals?from&to	GET /actuals	Response filtered to caller's personId before returning
GET /my/assignments	GET /assignments	Filtered to caller; used to know what projects/roles are valid targets
GET /my/projects	GET /projects (+ cache)	Only projects the caller is assigned to; names/ids only, no financials

5. Token Model & Lifecycle

Two token types, two worlds

	Runn account token	Broker user token
Issued by	Runn admin (Settings → API)	Broker admin endpoint / CLI
Lives in	Secrets manager on the broker host only	Client machines (CLI config, keychain)
Scope	Whole account (write)	One personId, allowlisted endpoints
Format	LIVE_… / TEST_…	Signed JWT: sub, personId, scope, exp, jti
Rotation	Set expiry at creation; rotate manually	Short-lived (e.g. 30–90 days) + revocation list by jti

Issuing a user token

# admin-only, on the broker host
$ broker-admin issue --email jan@company.com --person-id 4711 \
    --scope timesheet:write,timesheet:read --ttl 60d
→ eyJhbGciOiJIUzI1NiIs…   (hand to the user once, store hash of jti)

The mapping email → personId is resolved once at issue time (via GET /people) and baked into the token + a server-side record. The client never supplies it.

6. Security Rules (Non-Negotiable)

• Identity from token only. Any personId in a request body is ignored; if present and different, reject with 403 and log it.
• Allowlist, don't blocklist. Unknown routes and unknown upstream fields are dropped/rejected.
• Filter reads server-side. Upstream list endpoints return everyone's data; strip to the caller before responding.
• No financials pass through. Strip rates, costs, budgets from any upstream payload before it leaves the broker.
• Audit everything. One log line per request: ts, sub, jti, route, personId, upstream_status. This is also what makes your Runn admin comfortable issuing the account token.
• Secrets hygiene. Runn token in a secrets manager / env of the broker only, write-scoped, with an expiry date. Rotate on any suspicion.
• TLS + rate limits on the broker's public edge; per-token rate limiting to contain a leaked user token.

7. Runn API Quirks to Handle Centrally

• Pacing: Runn requires ~100ms between entries for the same person/project/role/date, or you get 429 Too many requests. The broker queues and spaces same-key writes.
• Zero-hour autofill: the first submitted actual back-fills 0h for all earlier assignment days. If a user starts mid-project, either accept the backfill or create the first actual via the UI first — the broker should document/flag this on first write per person/project.
• Versioning: always send Accept-Version: 1.0.0.
• Patch semantics: Runn PATCH only updates supplied properties; unset explicitly with null / "" / [].
• Test first: point the broker at a TEST_ token (Runn's test account) via config until the flow is proven; flip to LIVE_ by env var only.

8. Suggested Stack

• Service: FastAPI (Python) or Express/Hono (Node). ~200–300 lines for the surface above.
• Token store: SQLite is plenty — table of jti, sub, personId, scope, exp, revoked_at.
• Upstream client: thin wrapper with retry + pacing queue; single place that ever reads the Runn token.
• Deploy: anywhere private-ish (small VPS, internal host, or behind a tunnel). It does not need to be public — clients only need to reach it.