Appearance
Permissions
Every /api/v1 call is authenticated and authorized through teamusers. dispatchub keeps no local accounts: it verifies the bearer token locally against the issuer's JWKS and then resolves the caller's permissions remotely on every request - permissions are never carried inside the token.
The teamusers model
- teamusers is an Ed25519 (EdDSA) JWT issuer. Its JWKS lives at
{base}/.well-known/jwks.json; access tokens are short-lived (TTL 600 s by default). - Sign-in is
POST /auth/login {username,password}and returns an access token and a refresh token. Services instead usePOST /auth/client-credentials {client_id,client_secret}. - A principal is a user
{id, username, display_name, ...}plus an optional team. There is no teacher/class/campus model in teamusers: courses, rooms and teachers are dispatchub's own data. - A permission is a three-segment key, matched literally segment by segment. The only wildcard is
*, which matches exactly one segment.
The nine keys
dispatchub's catalog consists of three independent permissions, each with three scopes. None implies another:
| Key | Grants |
|---|---|
dispatch:read:<scope> | Read terms, rooms, import history, sessions, artifacts and live room status. |
dispatch:manage:<scope> | Create/update terms and 节次 tables; bind and unbind rooms; import timetables. |
dispatch:control:<scope> | Start and stop recordings, switch cameras, take snapshots. |
In full:
text
dispatch:read:any dispatch:read:team dispatch:read:own
dispatch:manage:any dispatch:manage:team dispatch:manage:own # terms, rooms, imports
dispatch:control:any dispatch:control:team dispatch:control:own # recording, camera switch, photoA teacher who records their own lessons needs dispatch:read and dispatch:control at own or team scope; an operator console needs dispatch:read:any plus dispatch:control:any; the administrator who maintains rooms and imports needs dispatch:manage as well.
The scope ladder
For every request dispatchub loads the target room (or the session's room) and builds the candidate key list broadest-first:
text
keys = ["dispatch:<action>:any"]
if room.team_id != "" and room.team_id == claims.team: keys += ["dispatch:<action>:team"]
if room.owner_id != "" and room.owner_id == claims.subject: keys += ["dispatch:<action>:own"]The first candidate the caller is allowed to use wins. None is implied by another:
anyneeds no relationship to the room.teamis only considered when the room'steam_idequals the caller'steam.ownis only considered when the room'sowner_idequals the caller'ssub.
team_id and owner_id are snapshotted onto the room row when the binding is created (PUT /api/v1/rooms/{room_code} reads them from the webcam-server device). That is why the binding is the source of truth for scope resolution: if the device's ownership changes upstream, re-bind the room to refresh the snapshot.
Collection and creation routes (GET /api/v1/rooms, GET /api/v1/sessions, GET/POST /api/v1/terms and the import routes) have no single room to compare against, so no team/own candidate is ever built for them: they require the any-scoped key (dispatch:read:any or dispatch:manage:any).
One route is a hybrid: PUT /api/v1/rooms/{room_code} treats a missing room as a create, so a new binding has no ownership snapshot and only dispatch:manage:any can grant it. Re-binding an existing room keeps its snapshot and accepts dispatch:manage:team / dispatch:manage:own through the same ladder.
Endpoint matrix
<scope> resolves through the ladder above.
| Route | Permission |
|---|---|
GET /api/v1/terms, POST /api/v1/terms | dispatch:read:<scope> / dispatch:manage:<scope> |
GET /api/v1/terms/{term_code}/periods, PUT .../periods | dispatch:read:<scope> / dispatch:manage:<scope> |
GET /api/v1/rooms | dispatch:read:<scope> |
PUT /api/v1/rooms/{room_code}, DELETE /api/v1/rooms/{room_code} | dispatch:manage:<scope> |
POST /api/v1/timetable/imports | dispatch:manage:<scope> |
GET /api/v1/timetable/imports, GET /api/v1/timetable/imports/{id} | dispatch:read:<scope> |
GET /api/v1/sessions, GET /api/v1/sessions/{id}, GET /api/v1/sessions/{id}/artifacts | dispatch:read:<scope> |
POST /api/v1/sessions/{id}/recording/start, POST /api/v1/sessions/{id}/recording/stop | dispatch:control:<scope> |
POST /api/v1/rooms/{room_code}/recording/start, POST /api/v1/rooms/{room_code}/recording/stop | dispatch:control:<scope> |
POST /api/v1/rooms/{room_code}/camera/switch | dispatch:control:<scope> |
POST /api/v1/rooms/{room_code}/photo | dispatch:control:<scope> |
GET /api/v1/rooms/{room_code}/live | dispatch:read:<scope> |
GET /healthz and GET /readyz are public.
The generated API reference repeats the permission for each operation through its x-teamusers-permission extension, which lists the any and team keys an endpoint accepts; because that extension has only those two slots, the own scope is documented on this page only.
Failure shapes
| Situation | Response |
|---|---|
| Missing, malformed or unverifiable token | 401 with the teamusers decision body {"allow": false, "reason": "..."} and WWW-Authenticate: Bearer realm="teamusers". |
| Verified caller, no candidate key allowed | 403 RFC 9457 problem detail with detail: "permission denied". |
| teamusers unreachable or erroring | 503 problem detail - dispatchub fails closed, never allows. |
Catalog registration
A permission key must exist in teamusers' catalog before a role can carry it. Register all nine once per deployment - either with the service subcommand:
sh
DISPATCH_TEAMUSERS_URL='http://127.0.0.1:8082' \
DISPATCH_TEAMUSERS_ADMIN_TOKEN='<teamusers admin token>' \
dispatchub register-permissionswhich needs those two variables alone - no database, no webcam-server endpoint and no service credential - and upserts each key with POST /permissions/ {key, description, registered_by}. The same registration by hand:
sh
TEAMUSERS_URL=http://127.0.0.1:8082
TEAMUSERS_ADMIN_TOKEN='<teamusers admin token>'
for key in \
dispatch:read:any dispatch:read:team dispatch:read:own \
dispatch:manage:any dispatch:manage:team dispatch:manage:own \
dispatch:control:any dispatch:control:team dispatch:control:own
do
curl -sS -X POST "$TEAMUSERS_URL/permissions/" \
-H "Authorization: Bearer $TEAMUSERS_ADMIN_TOKEN" \
-H 'Content-Type: application/json' \
--data "{\"key\":\"$key\",\"description\":\"SmartClass dispatch hub\",\"registered_by\":\"smartclass-dispatchub\"}"
doneAs a shorthand, one wildcard key per action (dispatch:read:*, dispatch:manage:*, dispatch:control:*) can be registered instead and bound wherever all three scoped keys would have been.
Service credential
dispatchub is itself a teamusers client. Its credential - DISPATCH_TEAMUSERS_CLIENT_ID / DISPATCH_TEAMUSERS_CLIENT_SECRET - authenticates the remote permission lookups behind every inbound request, and the same credential is exchanged for the outbound tokens used to call smartclass-webcam-server. The access token is cached and refreshed before it expires; a 401 from webcam-server triggers exactly one forced refresh and retry.
For dispatchub to command webcam-server, the credential's principal must be bound to a role that carries every cam:* key dispatchub uses. The union of the scope ladders it walks means the practical requirement is:
cam:read:any(device, stream, photo and segment reads)cam:control:any(recording start/stop, camera switch, snapshot)
Without them webcam-server answers 403 and the affected sessions fail with upstream_unavailable/permission denied details.
The same credential drives smartclass-merge, so it needs the two merge:* keys as well:
merge:write:any- create the merge job for a completed recording (POST /api/v1/merges). Creation has noownrung (a job that does not exist yet has no owner to compare against), and theteamrung only applies to a token carrying a team claim, so a service credential takes theanyscope.merge:read:any- poll the job (GET /api/v1/merges/{id}) while it isqueuedorrunning.
Both are needed because dispatchub both creates and follows the job, and merge resolves a single-job route against the job's scope before checking the caller's grants. Without them merge answers 403 insufficient_permissions; dispatchub then retries submission until the poll TTL expires and marks the merge failed - the recording and its segments are unaffected, but no merged video appears. When DISPATCH_MERGE_URL is empty these keys are unused: dispatchub creates no merge job at all.
The same credential also mints the merged video's presigned download_url, so it needs two filehouse keys on the destination bucket (recordings), where the merged objects live:
filehouse:share:any- authorizes minting a presigned URL at all (POST /api/v1/presign).filehouse:read:any- authorizes the read the minted URL exercises when it is redeemed (filehouse re-checks permissions on redemption and the URL is not single-use).
Both are required because filehouse evaluates the two grants separately against the bucket resource: share gates the mint itself, the exercised grant (read for a GET URL) gates the redemption. A credential holding only one of them gets 403 from the presign call, dispatchub logs the failure at Warn and omits download_url from the artifacts response - the merge object and every other field are still returned, so the caller sees a succeeded merge with no URL rather than an error. Scope the grants to the bucket where filehouse's policy allows it - dispatchub needs them only on the merge destination, not fleet-wide. When DISPATCH_FILEHOUSE_URL is empty the client is never built and these keys are unused.
Teacher identity
teacher_username is stored verbatim from the CSV. Where a token sub is needed - own scope, audit fields - dispatchub resolves it through a teamusers_identities(username, subject_id, synced_at) cache, filled on first successful lookup. If teamusers has no username-to-subject lookup endpoint available, teacher_user_id stays NULL and own-scoped access for that teacher degrades to team/any. This is a known open item; verify the lookup endpoint in your phase 0 before promising per-teacher self-service.