US-102: Invite New Users via Email¶

1. Story Title¶

Tenant admin invites user with email link

2. Context / Background¶

After initial tenant creation (US-101), admin must add collaborators efficiently.

3. User Persona¶

Primary: Priya – Tenant Admin / HR Manager Secondary: Invited User

4. Problem Statement¶

Manual user provisioning causes delays; no automated onboarding path.

5. Desired Outcome¶

Admin enters an email; system sends invitation with secure link enabling account creation & tenant join.

6. Business Value¶

Accelerates team onboarding; increases early activation & collaboration.

7. Scope (In / Out)¶

In: invitation creation, status tracking (Pending, Accepted, Expired), resend action. Out: Bulk CSV invite (future), role assignment UI (basic default only).

8. Acceptance Criteria (BDD)¶

Scenario: Create invitation
  Given Priya is on the user management page
  When she submits email bob@example.com
  Then an invitation with status Pending is stored
  And an email with activation link is sent

Scenario: Accept invitation
  Given a valid pending invite for bob@example.com
  When Bob clicks the link and sets password
  Then account is created
  And invite status becomes Accepted

Scenario: Expired invitation
  Given an invitation older than the expiry threshold
  When the link is used
  Then an expiration error is shown

Scenario: Resend invitation
  Given a pending invite
  When Priya clicks resend
  Then a new email is sent
  And audit event logged

9. UX Notes / References¶

Simple table: Email | Status | Created | Actions (Resend). Modal for invite form.

10. Data / Domain Model Impact¶

Invitation entity: email, token, status, createdAt, expiresAt.

11. NFR Touchpoints¶

Security: signed token scoped to tenant; one-time use.
Observability: InvitationCreated, InvitationAccepted events.
Performance: invite creation < 300ms.

12. Dependencies¶

US-101 tenant provisioning baseline.

13. Risks & Mitigations¶

Risk	Impact	Probability	Mitigation
Token leakage	Unauthorized access	Low	Short token TTL + invalidation on use
Email deliverability issues	Onboarding delay	Medium	Fallback manual copy link + monitor bounces

14. Estimation Support¶

Invitation model & repository
Email service integration
Accept endpoint
UI table & modal

15. Analytics / Success Metrics¶

Invite acceptance rate; average time from invite to acceptance.

16. Rollout / Release Strategy¶

Enable for internal tenants; monitor acceptance funnel; open to all.

17. Definition of Ready Checklist¶

Email template approved
Expiry duration decided

18. Definition of Done Checklist¶

All scenarios tested
Events visible in logs
Email template documented

19. Open Questions¶

Default invitation expiry (72h?)
Need reminder email automation?

Version: 1.0