How the Login Flow Works

From “send me a link” to a signed-in session — and every safeguard along the way.

1. Client request

1. On the login page, the client clicks the Magic Login Link button (injected by the ClientAreaHeadOutput hook, or your custom button HTML) and enters their email address in the modal.
2. The request is submitted to index.php?m=MagicLink&a=send. The module rate-limits the request by IP and by email (hsc_magiclink_rate_limits), and — if both WHMCS email verification and Verified Client Only are enabled — rejects unverified addresses.
3. A random 256-bit token is generated and stored as a hashkey in hsc_magiclink, together with the requester’s IP address and a SHA-256 hash of their User-Agent.
4. The Magic Link Request email is dispatched and both the request (token_requested) and the email send (email_sent) are recorded in the Activity Logs. A generic success response is shown regardless of whether the email exists.

2. Client login

1. The client opens the link: …/index.php?auth=<hash>. The ClientAreaPage hook intercepts the request and validates the token step by step:

3. On success the token is marked used, the Magic Link Security Alert email is sent (if enabled) and recorded (login_success + email_sent), the user’s consecutive-login counter is incremented, and the user is signed in through WHMCS CreateSsoToken — redirected to the configured fallback URL (default /clientarea.php).

3. Admin-generated links

When an admin sends a link from the Client Summary page or the client users dropdown, the same token machinery is used: previous active tokens are invalidated, a fresh 256-bit token is created, and the email is dispatched (token_sent_admin + email_sent). The generate URL variant returns a copy-paste link instead of sending email.

4. Housekeeping & safety nets

• Changing a client or user password expires all of that user’s active tokens (tokens_invalidated).
• Logging in with the normal password resets the consecutive magic-login counter.
• The daily cron prunes old tokens (PruneLogsDays) and old activity log rows (PruneActivityLogsDays).
• Invalidation and alert emails run in try/catch — a failure can never break WHMCS core flows (login, password change, cron).