Magic Link Authentication

Overview

Magic link authentication sends a one-time login link to the user’s email. No password required — possession of the email inbox proves identity.

Flow

1. User enters email on the auth service login page

2. Auth service sends email with a verification link containing a one-time token

3. User clicks link in their email

4. Auth service verifies token, creates user if needed, issues authorization code

5. Redirect back to the client app with the code

Endpoints

Send Magic Link

POST https://auth.beshoy.ai/auth/magic-link/send
Content-Type: application/json

Field	Type	Required	Description
email	string	Yes	User’s email address
project_id	string	Yes	Target project
redirect_uri	string	Yes	Where to redirect after auth
code_challenge	string	Yes	PKCE S256 challenge
state	string	Yes	Opaque state to return

Verify Magic Link

GET https://auth.beshoy.ai/auth/magic-link/verify?token=xxx

This is the link the user clicks in their email. The auth service:

1. Retrieves the token data from KV
2. Verifies it hasn’t expired (15-minute TTL)
3. Creates the user if they don’t exist (unless registration is closed)
4. Adds the user to the project if not already a member
5. Marks the user’s email as verified
6. Issues an authorization code
7. Redirects to the client with code and state

Email Delivery

Magic links are sent via the Resend email API. The email contains:

• A branded template matching the project’s branding
• A single call-to-action button with the verification URL
• 15-minute expiry notice

Rate Limiting

• 3 magic link sends per hour per email address
• Prevents email bombing / spam

Note

The rate limit is per email, not per IP. This prevents an attacker from sending unlimited emails to a victim from different IPs.

Auto-Registration

Unlike password auth, magic links can create new users automatically:

• If registration = "open" → user created on first magic link verification
• If registration = "invite_only" → user must already exist or have an invitation
• If registration = "closed" → user must already exist

New users created via magic link have email_verified = 1 (since they proved inbox access).

Token Storage

Magic link tokens are stored in KV with:

• Key: magic:{random_token}
• Value: { email, project_id, redirect_uri, code_challenge, state }
• TTL: 900 seconds (15 minutes)

Tokens are deleted after use (one-time).

Error Responses

Error	Cause
Rate limited	3+ sends in the last hour for this email
Invalid or expired token	Token not in KV (expired or already used)
Registration closed	New user + project registration is closed