MFA & notifications
Summarized from IDENTITY-MFA-NOTIFICATIONS-AND-BRANDING.md. Canonical auth spec — phases P1–P4 done, P5 partial, P6 done (MVP).
Locked decisions
| Topic | Decision |
|---|---|
| Email verification | Required at signup (all human accounts) |
| MFA enrollment | TOTP (authenticator app) required after grace period |
| MFA at login | User may complete challenge via TOTP, SMS OTP, or email OTP (configurable preference) |
| MFA grace period | 7 days after signup before MFA is mandatory |
| Remember device | Allowed (~30 days), then full MFA again |
| TE platform billing brand | TenancyEngine (billing.tenancyengine.com, @tenancyengine.com email) |
| TenaBill-only merchants | TenaBill default brand; org may configure custom domain |
| SendGrid | Subaccount per TenaBill merchant; send from merchant subdomain by default |
| Human auth UI | account.tenancyengine.com (and env variants) |
| OIDC issuer (machine) | auth.saasruntime.com — unchanged in SDKs and APIs |
| Dev notifications | Mailpit SMTP; dev SMS via API log lines |
Domain map (human-facing)
| Surface | Production host | Audience |
|---|---|---|
| TE marketing | tenancyengine.com | Public |
| TE console | console.tenancyengine.com | ISV / platform operators |
| Account / MFA / security | account.tenancyengine.com | All OIDC users |
| TE billing portal | billing.tenancyengine.com | ISVs paying for TE |
| TenaBill merchant console | console.tenabill.com | TenaBill merchants |
| TenaBill customer portal | portal.tenabill.com or merchant CNAME | End customers |
Signup & MFA flows
Signup methods
- Email + password (with email verification before full access)
- Email magic link
- Google / Microsoft (social)
- SMS-assisted signup optional later
Post-signup
- User has 7-day grace — can use product with verified email only.
- Before grace ends (or on day 8), user must enroll TOTP on
account.tenancyengine.com. - User sets preferred login challenge: TOTP (default), SMS, or email OTP.
- Optional: enroll SMS phone and/or backup codes.
Every login (after MFA enrolled)
- Primary auth (password, magic link, or social).
- MFA challenge via preferred method (TOTP / SMS / email OTP).
- Optional "remember this device" (30 days).
- Redirect to originating client (
console.tenancyengine.com, app,console.tenabill.com, etc.).
Audit events
Log email.verified, mfa.enrolled, mfa.challenge, login.success, login.failed, social.linked, device.remembered.
Security UI by surface
| Surface | Security capabilities |
|---|---|
| Account hub | Email verification, TOTP QR enrollment, SMS phone, preferred MFA method, backup codes, linked social accounts, active sessions, change password |
| TE console | Settings → Security (deep-link to account hub); Billing → billing.tenancyengine.com |
| TenaBill merchant console | Settings → Security; branding → custom domain / SendGrid subaccount status |
| TE billing portal | Invoices, payment methods; step-up MFA for payment changes |
Email & SendGrid branding
Platform (TenancyEngine merchant on TenaBill)
- From:
noreply@tenancyengine.com,billing@tenancyengine.com,security@tenancyengine.com - Portal:
billing.tenancyengine.com(white-label theme) - No "Powered by TenaBill" footer
TenaBill standalone merchant
- Create TenaBill
Merchanton signup - Provision SendGrid subaccount (API) for merchant
- Default sending domain:
{merchant-slug}.mail.tenabill.com - Merchant console → Branding: logo, colors, optional custom domain
- Show "Powered by TenaBill" only when no custom domain and merchant is not a platform white-label merchant
Implementation phases
| Phase | Deliverable | Status |
|---|---|---|
| P1 | TenancyPlatform.Notifications — IEmailSender, ISmsVerifier; Mailpit dev | Done |
| P2 | Email verification, account hub, TOTP enrollment, 7-day grace | Done |
| P3 | SMS + email OTP challenge providers (Twilio + SendGrid) | Done (MVP) |
| P4 | Google + Microsoft external login + post-login MFA | Done (MVP) |
| P5 | OIDC clients: TE console, TenaBill console; account proxy | Partial |
| P6 | TenaBill SendGrid subaccount on merchant signup | Done (MVP) |
| P7 | White-label billing.tenancyengine.com + TE SendGrid templates | Planned |
| P8 | Customer portal magic link via merchant-branded SendGrid | Planned |
Local testing
See Local development for Mailpit, MFA enrollment URLs, and OIDC test flows.