Platform guide

1The hierarchy

Two hierarchies, deliberately separate. A user is platform-wide; access is per tenant. One person is one row with one password, and holds a membership in each tenant they may act in — which is what makes a consultant serving three clients one account rather than three.

The second dimension is corridor scope, which narrows a membership, not a role:

2Cold start you

From an empty database to a working platform admin. This is the only path that creates an account no route can create: every user-creating route needs tenant:admin, which needs a membership, which needs somebody to have granted one. On a fresh database nobody has.

1. Apply the migrations (Postgres only)

   All of them, in filename order. They are idempotent, so re-running is safe — applying a subset is not.

   for f in deploy/sql/*.sql; do psql -v ON_ERROR_STOP=1 -f "$f"; done

   On SQLite the schema is created at import; nothing to run.

2. Register the reserved tenant

   export ROADINTEL_DB_URL="$(python -m app.dburl)"
   PYTHONPATH=. python scripts/manage_tenants.py create --id _platform --name Kologic

   _platform fails the tenant-id regex on purpose — a leading underscore is what keeps it out of the space real tenants draw from — and is exempted by name, so _anything_else is still rejected. The row must exist because memberships reference it ON DELETE RESTRICT.

3. Create the first platform admin

   PYTHONPATH=. python scripts/bootstrap_admin.py \
       --email ops@kologic.ai --tenant _platform --name "Platform Ops"

     user     u_9e5aaa91c2ae  (ops@kologic.ai)
     tenant   _platform · platform_admin  (no client tenant)
     invite   aWNlV5kxfI_FFHq2SXcJ1BZ8pMoNvR3tYgKdWuE7LxA
     expires  in 48 h

   --tenant _platform makes a pure platform admin with no client membership — the right shape, since a platform admin who is also somebody's tenant admin has a wider blast radius than the role needs. To make someone both, name the client tenant and add --platform.

   The invite is printed once. It is stored only as a hash and there is no mail in this estate — hand it over out of band. And bootstrap a second platform admin before you rely on the first: one lost password is otherwise a lockout with no in-product recovery, because _platform holds the memberships you would need to undo it.

4. Redeem, and confirm

   Open /login?code=<the code>, or:

   curl -sX POST /auth/redeem -H 'content-type: application/json' \
     -d '{"token":"<the code>","password":"<a strong one>"}'

   Redeeming sets the password, flips the account from invited to active, and signs them in. Single use. If it lapses, re-run the bootstrap — it re-invites rather than duplicating the account.

3Onboard a tenant you

Three moves: register it, give it corridors, invite its admin. After that the tenant runs itself — their admin creates their own people.

A tenant id becomes an S3 key prefix (clips/{tenant}/{session}/…), so it must match ^[a-z0-9][a-z0-9-]{1,38}[a-z0-9]$.

curl -sX POST /platform/tenants/acme/corridors -b jar \
  -H "x-roadintel-csrf: $CSRF" -H 'content-type: application/json' \
  -d '{"id":"NH16","name":"NH16 Vizag",
       "centreline":[[83.2,17.7],[83.3,17.75],[83.4,17.8]]}'

centreline takes the points directly; road_id traces an existing reference route instead.

curl -sX POST /platform/tenants/acme/users -b jar \
  -H "x-roadintel-csrf: $CSRF" -H 'content-type: application/json' \
  -d '{"email":"boss@acme.com","role":"admin"}'

{"user_id":"u_…","email":"boss@acme.com","role":"admin","created":true,
 "invite_token":"UQPXYNezY1VjTY…",
 "note":"Shown once. Not stored, not emailed — hand it over out of band."}

4Build a team you

Done by the tenant's own admin at Access. Identical contract to the platform routes, so there is one rule to learn rather than two.

# an operator
POST /admin/users  {"email":"driver@acme.com","role":"operator"}

# a delegated sub-admin, narrowed to one corridor
POST /admin/users  {"email":"lead@acme.com","role":"sub_admin",
                    "scope_corridors":["NH16"]}

Optional fields: display_name, expires_at (an ISO stamp — the membership lapses on its own, with nothing to run) and scope_corridors.

Custom roles

The four built-ins are seeded per tenant on first membership. A tenant may define its own from the 28-key permission catalogue — GET /platform/permissions lists it, and five of those keys are enforced by nothing and are marked so rather than quietly omitted. A role the tenant has not defined is refused by a foreign key, so a typo is a database error rather than a silent no-access account.

5Delegation & corridor scope

What a sub_admin scoped to ["NH16"] may and may not do — every row below verified end to end.

| email          | tenant | role      | scope_corridors      |
| boss@acme.com  | acme   | admin     | NULL (all corridors) |
| lead@acme.com  | acme   | sub_admin | ["NH16"]             |
| heir@acme.com  | acme   | operator  | ["NH16"]   <- inherited

Scope is enforced in two places, and both are needed: the scoped repo narrows corridor-keyed reads, so a route that forgot its guard still cannot return another team's rows; and the request guard refuses any path carrying an out-of-scope corridor id.

6Day to day you

All under Platform, all platform_admin unless marked otherwise.

Suspending a user is platform-wide; revoking a membership is not. Different blast radii, and the console keeps them apart. Suspending a tenant refuses every request carrying it but does not revoke sessions — reinstating restores access with no new sign-in.

7Emergency login you

Mints a session as a user in a tenant. Deliberately separated from ordinary administration in the console — a red control, not a row action — because impersonation and management are different acts with different consequences.

POST /platform/tenants/{id}/emergency-login

It rotates: a new session is minted and the previous revoked, with rotated_from recording the change, so a cookie stolen before the switch is dead. Use it to reproduce what a client sees — not as a shortcut for support.

8Offboarding you

Suspends the tenant, revokes every membership and every machine token, and purges nothing. Reversible.

POST   /platform/tenants/{id}/export     # first
DELETE /platform/tenants/{id}            # then

In the console both live in the tenant's Settings tab, side by side, because export-before-delete is one workflow and separating them invites doing the second without the first.

9Traps & gaps

Stated because a guide that omits its holes is the more dangerous document.

Known gaps

• Object-id-keyed writes are not corridor-scoped. Retracting a batch, saving a survey, updating a work order and saving a capture session are keyed by a child object id, so neither enforcement layer can narrow them: a scoped sub_admin who learns an out-of-scope batch id can still retract it.
• Machine tokens have never been exercised end to end since the load balancer stopped stripping them.
• Work orders are the only lifecycle with no database CHECK — a bad status is stored rather than refused.
• Three permissions have no subsystem behind them — AI reports, billing and camera registration — not merely no guard.

Deeper reference lives in the repository: DOMAIN-MODEL.md (what the entities are), STATE-MACHINES.md (their lifecycles), RBAC-MATRIX.md (the authoritative permission table, generated from the code) and PLATFORM-GUIDE.md.