users-auth-service — business features

1. What it is

users-auth-service decides who you are and what company you belong to: it signs everyone in (admins by password or one-time code, employees by SMS/email code, Oper staff by password plus authenticator app), and it owns the records every other service asks about — companies, people, groups, work locations, job titles, plans, invoices and AI credits. It is also the only service on the public ingress (auth.useoper.com), so it doubles as the front door: the mobile app, the admin web app and the internal back office all talk to it, and the back office's authoring screens are proxied straight through it to authoring-service-v2.

The two satellite workers live here on purpose: their code is users-auth-service/app/otp_worker/ and users-auth-service/app/onboarding_enrichment/, they ship in this service's image, and they only get their own Deployment (k8s/otp-worker-deployment.yaml:61, k8s/onboarding-enrichment-worker-deployment.yaml) so a slow Mailgun call or an LLM call can never sit on the API's event loop. The top-level otp-worker/ and onboarding-enrichment-worker/ directories are empty shells — no tracked source, only __pycache__, tests and stale k8s copies (ARCHITECTURE.md:44). Documenting them here, with this service, is therefore the whole story.

2. Feature map

flowchart LR
  ADMIN["Tenant admin (web app)"]
  EMP["Employee (mobile app)"]
  STAFF["Oper staff (back office)"]
  SVC["Other backend services"]
  SCHED["Schedulers (cron + in-pod loops)"]

  ADMIN --> IDENT["Sign-in, 2FA, sign-up, onboarding (/v1/admin/*)"]
  ADMIN --> PEOPLE["People, groups, locations (/v1/admin/:tenant/*)"]
  ADMIN --> MONEY["Plans, invoices, AI credits (billing, credits)"]
  ADMIN --> COMPLY["GDPR export, deletion queue (exports, deletion-requests)"]
  EMP --> MOBILE["Employee OTP, profile, update gate (/v1/mobile/*)"]
  STAFF --> BACKOFFICE["Tenant 360, billing ops, authoring proxy (/v1/oper-admin/*)"]
  SVC --> INTERNAL["Token check, tenant + people lookups, credit gate (/v1/internal/*, JWKS)"]
  SCHED --> JOBS["OTP worker, enrichment worker, 3 reconcilers, GDPR cron"]

3. Features

Admin

Oper staff (back office)

Employee (mobile)

Internal (other services)

Background

4. API reference

Every route the scanner found, in scan order (147 rows — the row count matches tools/feature-docs/out/users-auth-service.json). “Auth” is what the handler actually enforces, not what the prefix suggests: the admin panel authenticates with the oper_sess session cookie (not a bearer token), and mutating admin routes additionally require a multi-admin scope resolved from the caller's role (app/routes/admin_login.py:102-161, libs/auth/oper_auth/scopes.py).

Registration is mounted twice. public_registration_router is included at the canonical /v1/admin/registration (app/main.py:304) and again at the deprecated, schema-hidden /v1/public/admin (app/main.py:306). Both prefixes reach the same four handlers; the alias rows carry their own verdict.

Three live routes the scan misses

The scanner resolves neither empty-string paths (@router.get(""), which inherit the router prefix whole) nor @router.api_route, so these three are absent from the JSON above and are listed separately to keep that table row-for-row with the contract. One of them is the single most-used entry point on the staff console.

Evidence: app/routes/internal_app_versions.py:133 (operator read of the current floors, paired with the PUT above and named in docs/fe-app-update-gate.md:157) · app/routes/oper_backoffice.py:51 (the staff tenant directory, docs/fe-backoffice.md:123, :195) · app/routes/oper_authoring.py:369 (the back-office authoring catch-all, docs/fe-backoffice.md:130, :153-190).

5. Async contracts

All identity traffic rides one stream, AUTH (auth.>, users.*, tenants.*), which this service creates at boot (nats/init.sh:19-31, ConfigMap k8s/nats-screams-cm.yaml:24). The TENANTS and USERS stream definitions still sitting in that ConfigMap are never created — the init script says so in as many words (nats/init.sh:32). The otp-worker mounts this service's init script rather than shipping its own (k8s/otp-worker-deployment.yaml:43).

Consumes

The users.* consumer reacts to five of the subjects it receives (created, updated, enabled, disabled, deleted) and acks the rest (app/services/groups_events_subscriber.py:36-47). Its durable is a pull consumer with max_deliver=4; anything that ends up undelivered is picked up by the dynamic-groups reconciler. The five otp-worker durables are derived from the subject name at subscribe time (app/otp_worker/processor.py:122), so the names above are exact, not templates.

Publishes

Evidence, publishers: app/routes/admin_login.py:320, :565, :861 · app/routes/mobile_login.py:86, :100, :108 · app/routes/users.py:222, :227, :234, :249 · app/routes/admin.py:67, :197, :282 · app/routes/admin_company.py:134 · app/routes/admin_onboarding.py:49, :56 · app/routes/admin_billing.py:199 · app/routes/public_registration.py:157 · app/routes/groups.py:851 · app/routes/mobile_profile.py:218 · app/services/gdpr_export.py:350 · app/otp_worker/processor.py:389 (DLQ) · app/onboarding_enrichment/processor.py:364. Consumers: notification-worker/app/core/config.py:115 (admin envelopes), authoring-service-v2/app/consumers/register.py:68 (usage), app/services/groups_events_subscriber.py:143 (users.*). The two training.notifications.ten.*.admin.* rows in the scan output are one f-string subject each — the literal subject is training.notifications.ten.<tenant_id>.admin.<type>, which the notification-worker filter matches token-for-token. users.* also reaches feed-service's event mapper, but feed consumes nothing at all (ARCHITECTURE.md §4.1(5)), so that edge does not make anything live.

Background jobs

All three reconcilers replaced earlier k8s CronJobs and are started from the app lifespan (app/main.py:144-146); the groups subscriber at app/main.py:135. Every start is wrapped so a bring-up failure cannot block the API, which also means a silently unstarted loop looks identical to a healthy one in the logs.

6. Data it owns

Postgres database users_auth, 31 alembic revisions, and—unusually for this platform—no second writer: every other service reads this data over HTTP (ARCHITECTURE.md §3.4). The Postgres and Redis instances themselves are platform-shared despite their auth-scoped names, and this service's k8s manifests are what create them.

No table here is written by another service, and this service writes into no other database. The shared postgres-db-init-job.yaml in this repo's k8s/ directory still creates three databases nothing references (certificates, progress, authoring_db — ARCHITECTURE.md §3.4).

7. Dependencies

flowchart LR
  ML["micro-learning"] --> UA
  AS["assignment-service"] --> UA
  AV2["authoring-v2"] --> UA
  NW["notification-worker"] --> UA
  FS["feed-service"] --> UA
  OEW["onboarding-enrichment-worker"] --> UA
  UA["users-auth-service"] --> ML
  UA --> AS
  UA --> NW
  UA --> FS
  UA --> AV2
  UA --> EXT["Stripe · Twenty CRM · Sentry"]
  OTP["otp-worker"] --> SEND["Mailgun · Twilio"]
  UA -. "AUTH stream" .-> OTP
  UA -. "AUTH stream" .-> OEW

Inbound (all with X-Oper-Key): micro-learning for users, directory, preferences and the credit debit at publish (H11-12); assignment-service for groups, members, profiles and token validation (H15); authoring-v2 for tenant info, profile batch and the credit gate (H4); notification-worker for tenant admins and preferences (H25); feed-service for users and profiles; the onboarding worker for its result POST (H27). Outbound: micro-learning analytics, billing and training stats (H19, also on the GDPR cron and the mobile /me path); assignment-service user assignments and activity (H20); notification-worker active devices (H21); authoring-v2 through the back-office proxy (H22) and the pipeline reads; and the GDPR export fan-out to four services (H23). Note the prefix trap: authoring-v2 exposes /internal/v1/* while everyone else uses /v1/internal/* (ARCHITECTURE.md §3.2).

8. Dead-code verdicts

Every entry point with no in-repo caller. Deleting is a separate decision — see the hub roll-up.

Two report findings are now stale rather than open, which is worth recording so nobody re-opens them: bug-hunt #14 (“NATS groups subscriber runs sync psycopg2 on the event loop”) no longer matches the code — the blocking work is on a worker thread and the docstring explains why (app/services/groups_events_subscriber.py:50-58); and the report's premise that the dynamic-groups sweep is a k8s CronJob (#10, #17) is superseded by the in-process reconcilers (app/services/reconcilers.py:1-38), though the SAVEPOINT fix it asked for is in place. Everything else in that report is still open and is linked from the feature it belongs to.

9. Sources

• tools/feature-docs/out/users-auth-service.json — the scanned entry-point contract (147 routes, 7 consumers, 20 published subjects, 5 background tasks).
• ARCHITECTURE.md §1 (ingress), §2 (service inventory, empty shells), §3.2 (HTTP edges H4, H11-12, H15, H19-23, H25, H27), §3.3 (AUTH stream), §3.4-3.5 (databases, Redis indices), §4.1 (live defects).
• bug-hunt-reports/users-auth-service.md — 20 findings; #2, #5, #10, #11, #16 fixed, the rest open. Cross-referenced, not re-derived.
• bug-hunt-reports/otp-worker.md — #2, the DLQ publish-after-ack loss.
• docs/admin-frontend-integration.md — sign-in, TOTP, registration, and the /v1/public/admin → /v1/admin/registration deprecation table.
• docs/admin-token-refresh-integration.md — silent refresh, and “don't call /v1/auth/refresh from the admin panel; it exists for the mobile flow”.
• docs/admin-onboarding-integration.md — the five-step wizard and the enrichment contract.
• docs/admin-groups-integration.md — static vs dynamic groups, preview and resolve.
• docs/admin-locations-integration.md — locations list, filters, bulk delete.
• docs/fe-multi-admin-team.md and docs/fe-admin-role-permissions.md — OWNER/ADMIN/EDUCATOR, one endpoint family for every kind of user, and per-surface permissions.
• docs/fe-admin-user-details.md — the four cards on a learner's page.
• docs/fe-admin-billing.md — the MAU pricing model, admin billing screens and the staff billing endpoints.
• docs/fe-admin-company-settings.md and docs/fe-admin-profile.md — company and personal settings.
• docs/fe-admin-gdpr-export.md and docs/fe-account-deletion.md — the two privacy workflows.
• docs/fe-app-update-gate.md — the 426 gate contract and the operator runbook.
• docs/fe-backoffice.md — the staff console: tenant directory, tenant 360, and the authoring proxy (including what is not proxied).
• docs/otp-worker.md and docs/onboarding-enrichment-worker.md — the two satellite workers that live in this service's image.
• New-Design/SDD-multi-admin.md, New-Design/SDD-credit-ledger.md, New-Design/SDD-trial-and-enterprise.md, New-Design/SDD-admin-notification-centre.md — designs of record for roles, credits, trials and the admin inbox.
• Caller evidence read directly from source: authoring-service-v2/app/core/http.py, micro-learning-service-v2/app/clients/*.py, assignment-service/app/services/{users,groups}_service.py, notification-worker/app/services/{admins_client,preferences_service,admin_notification_service}.py, feed-service/app/clients/users_auth_client.py, libs/auth/oper_auth/token_validation.py.