City Portal & Magic-Link Auth

City compliance officers don't want another password. The Levy city portal at /city/{slug} uses email-based magic-link auth — enter your email, click a link, you're in. The session is HMAC-signed, lasts 24 hours, and is scoped to a single jurisdiction.

URL structure

The slug matches mds_jurisdictions.slug. One slug = one jurisdiction = one bbox.

Magic-link flow

What the contact sees

The dashboard shows:

• Compliance scoreboard — pass/fail per permit_conditions row, 30-day rolling
• Today's snapshot — deployed fleet count, trips, open complaints
• Active policies — the rules ingested from their own Policy feed (sanity check)
• Links — to fleet map, trip heatmap, parking corrals, monthly report

Everything below the snapshot is read-only. The portal does not let the city edit operator data — they edit their own policy feed, and we re-ingest it.

Bbox clipping

Every city-portal API route is clipped to the jurisdiction's bbox before returning data. The clipping is enforced server-side, not at the UI layer:

// Inside every /api/city/{slug}/* route
const session = await verifyCitySession(request);
const jurisdiction = await getJurisdiction(session.jurisdiction_id);
const bbox = jurisdiction.bbox; // [minLng, minLat, maxLng, maxLat]

const vehicles = await sb
  .from('vehicles')
  .select('id, last_lat, last_lng, status, vehicle_number')
  .gte('last_lng', bbox[0])
  .lte('last_lng', bbox[2])
  .gte('last_lat', bbox[1])
  .lte('last_lat', bbox[3]);

A city contact will never see a vehicle outside their boundary, even if it exists in the same subaccount.

For the trip heatmap, clipping is performed on the trip's start point — a trip that began inside the jurisdiction and ended outside still appears on the heatmap. This is what cities expect for trip-origination analytics.

Session expiry + refresh

Sessions last 24 hours. There is no refresh flow — the contact requests a new magic link when the session lapses. This is deliberate: a city analyst losing access for a few hours and going through the magic-link motion again is acceptable; long-lived city portal sessions are not.

The HMAC secret can be rotated by setting a new value in environment config and redeploying. Sessions signed with the old secret immediately fail HMAC verification and the contact gets a clean re-login prompt.

Multiple contacts per jurisdiction

A jurisdiction can have any number of city_contacts rows. Common pattern:

All three see the same data, all three receive digest emails on their own cadence. Sessions are independent — one contact logging out does not affect the others.

Revoking access

To revoke a contact's access:

1. Open /dashboard/compliance/{jurisdiction-id} -> City contacts.
2. Set portal_access = false on the row, or delete it outright.
3. Active session cookies on that contact will fail server-side verification at the next request — the cookie is still valid HMAC, but the contact row no longer permits portal access.

Magic links already minted to that contact are also invalidated — auth/callback rejects tokens for contacts where portal_access = false.

Localization

The portal is rendered in the contact's language preference (city_contacts.locale, defaults to en). Digest emails also use the same preference. Launch supports en and es; additional locales fall back to English.

Troubleshooting

• Contact says "didn't get the email" — check spam, then confirm the email matches city_contacts.email exactly (case-insensitive). Re-send by entering the email in the portal form again.
• Link says "expired" — magic links live 15 minutes. The contact should request a new one.
• Link says "invalid" — the token was already consumed, the contact row was deleted, or portal_access was set to false. Investigate in the operator dashboard.
• Session cookie not setting — the contact is on a browser that blocks third-party cookies and /city/{slug} is being loaded inside an iframe somewhere. Avoid iframe embeds.

What's next

• Digest Emails and Cadence — what the contact receives in their inbox.
• Permit-Condition Reports — what the dashboard scoreboard is checking.