US-103: Magic Link Account Creation

1. Story Title

Invited user activates account using magic link

2. Context / Background

Complements US-102: frictionless account creation avoids manual credential setup complexity.

3. User Persona

Primary: Invited User Secondary: Tenant Admin (monitoring status)

4. Problem Statement

Standard signup plus code entry friction reduces acceptance conversion.

5. Desired Outcome

User clicks magic link; token auto-validates and directs to lightweight password/set profile screen, joining tenant instantly.

6. Business Value

Improves onboarding speed and reduces support overhead for new users.

7. Scope (In / Out)

In: single-use token, direct activation flow, minimal profile step (name). Out: Multi-factor auth (future), progressive profile completion.

8. Acceptance Criteria (BDD)

Scenario: Valid magic link activation
  Given a pending invitation with magic token
  When user navigates to link within validity window
  Then token is validated
  And user sets password & name
  And tenant membership is confirmed

Scenario: Reuse blocked
  Given a token already used
  When user attempts second activation
  Then an invalid/expired message is shown

Scenario: Expired token
  Given token past expiry
  When user clicks link
  Then system prompts for resend flow

Scenario: Missing required profile field
  Given user left name blank
  When submitting activation
  Then validation error is shown

9. UX Notes / References

Activation page: greeting, token validation spinner, form (Name, Password), submit.

10. Data / Domain Model Impact

Reuses Invitation; adds activation timestamp field.

11. NFR Touchpoints

• Security: short TTL (e.g., 24h), hashed tokens.
• Observability: ActivationFailed reasons.
• Performance: token validation < 200ms.

12. Dependencies

US-102 invitations.

13. Risks & Mitigations

Risk	Impact	Probability	Mitigation
Token brute-force attempt	Unauthorized access	Low	High entropy tokens + rate limiting
User abandons after token success	Lower conversion	Medium	Minimal required fields + progress indicator

14. Estimation Support

1. Token validation endpoint
2. Activation form & flow
3. Post-activation redirect
4. Events instrumentation

15. Analytics / Success Metrics

Activation completion rate; mean time on activation page.

16. Rollout / Release Strategy

Pilot with internal invites; expand.

17. Definition of Ready Checklist

• TTL confirmed
• Password policy aligned with US-101

18. Definition of Done Checklist

• All scenarios covered by tests
• Metrics visible in dashboard

19. Open Questions

1. Offer optional avatar upload at activation?
2. Should we auto-generate display name from email prefill?

---

Version: 1.0