2.4 First tenant admin user

Outcome

The customer's IT/billing lead can log in at their subdomain with a tenant admin role and create their own users from there.

Prerequisites

• 2.3 Subdomain and TLS complete.

How (impersonation pattern)

Tenant users live inside the tenant DB. Platform admins can't insert directly via the Admin UI — they impersonate the tenant first, then use the tenant's own user-management UI. Impersonation itself requires a fresh step-up MFA verification on the platform side; you will be prompted for your TOTP code or WebAuthn touch before the impersonation JWT is issued.

Impersonation is a cross-origin handoff since the platform console became its own application: admin-service mints a 30-second pointer, rcm-core redeems it once on the customer's own origin and issues the tenant session. See Impersonate a tenant for the full flow and the one known gap in it.

Steps

1. Open the tenant in the Admin UI

   Admin → Tenants → Acme Behavioral Health → Switch to tenant. Confirm the modal that explains every action will be audited under your platform user ID.

2. Create the first tenant admin

   In the now-impersonated UI:

   Settings → Users → Add user

   Field	Value
   Email	The customer's IT lead's email
   Display name	Their name
   Role	TENANT_ADMIN
   Force password change on first login	yes

   The system generates a one-time password and shows it once. Send it via your secure channel (1Password, SecureSend, etc.). On first sign-in the customer will be issued a short-lived mfa_enrollment JWT and required to enroll TOTP (and optionally WebAuthn) before a full tenant JWT is granted — see the tenant MFA policy editor if you want stricter or looser per-tenant enforcement.

3. Confirm the user can sign in

   Have the customer sign in to acme.rcm.medsuite.com and change their password.

4. Exit impersonation

   In the Admin UI, click Stop impersonating.

5. Verify the audit trail

   -- Master-side audit shows your impersonation
   SELECT event_type, ts, details
   FROM identity.tenant_audit
   WHERE tenant_id = '<acme tenant_id>' AND ts > now() - interval '1 hour'
   ORDER BY ts;

   You should see IMPERSONATION_STARTED, the user-creation events (also captured on the tenant side), and IMPERSONATION_ENDED.

Roles to know

Role	What they can do
TENANT_ADMIN	Manage users, roles, all tenant config.
BILLING_LEAD	Manage payers, fee schedules, claims, denials.
BILLER	Day-to-day claim work; cannot change config.
READONLY	View only.

The customer's TENANT_ADMIN will go on to create the rest of their team in 2.10 Users + RBAC.

Validation

Check	Expected
Tenant security.app_user count	1
security.user_role for that user	TENANT_ADMIN
Login at acme.rcm.medsuite.com	succeeds
identity.tenant_audit IMPERSONATION_STARTED + ENDED	both present

Troubleshooting

Symptom	Likely cause	Fix
Impersonation token returns 403 on writes	Tenant status is read_only or suspended	Confirm identity.tenant.status='active'.
Created user can't log in	Slug missing from URL	Sign in via acme.rcm.medsuite.com, not the bare host.
Email is correct but login fails	Password copy/paste includes whitespace	Re-issue via Settings → Users → Reset password.

Next

2.5 — Org and facilities