Magic Links

Magic links provide passwordless authentication — the user enters their email, receives a link, and clicking it authenticates them without a password.

Just want a login form?

If you don't need to build the UI yourself, the <allegro-login-form> web component handles the entire magic link flow out of the box — drop one tag on your page and you're done.

How It Works

1. Call allegro.member.requestMagicLink(email) — Allegro sends a magic link to that address and starts polling for authentication in the background
2. The user clicks the link, which includes a short-lived token in the URL
3. The SDK automatically detects allegro_token in the URL and validates it
4. On success, a JWT session is issued and allegro:magic-link:authenticated fires on window

Requesting a Magic Link

await allegro.member.requestMagicLink(
    '[email protected]',
    'https://example.com/account', // optional: where to redirect after auth
    { plan: 'monthly' }, // optional: custom data attached to the request
);

Parameter	Type	Required	Description
email	string	Yes	The user's email address
returnUrl	string	No	URL to redirect to after the magic link is validated. Defaults to the current page.
data	Record<string, unknown>	No	Custom data to attach to the request

important

returnUrl must be an allowed origin

For security, returnUrl must point at an origin the tenant has allowed — its Allegro subdomain, its custom domain, or any origin in the cors_allowed_origins tenant setting. A request whose returnUrl is on any other origin is rejected with a validation error and no magic link is sent. This stops the sign-in token from being delivered to a domain you do not control.

Because returnUrl defaults to the current page, embeds served from your own site work without extra configuration. You only need to add origins when you redirect to a different host.

Calling requestMagicLink automatically starts cross-tab polling so that if the user opens the magic link in a different browser tab or window, the original tab authenticates without a page reload.

Validating a Token Manually

The SDK validates allegro_token from the URL automatically on page load. If you need to validate a token yourself:

const { jwt } = await allegro.member.validateMagicLink(token);

SDK Events

All events are dispatched on window as CustomEvent instances.

Event	Detail	When
allegro:magic-link:authenticated	(none)	Token validated successfully, or polling detected auth in another tab
allegro:magic-link:failed	{ error: string }	Token validation failed (expired or invalid)
allegro:jwt-refreshed	MemberJwtPayload	JWT was refreshed successfully
allegro:jwt-refresh-failed	{ error: string }	JWT refresh failed
allegro:logout	(none)	User was logged out
allegro:ready	(none)	SDK fully initialized (fires before magic link validation)

window.addEventListener('allegro:magic-link:authenticated', () => {
    // User is now authenticated — update your UI
});

window.addEventListener('allegro:magic-link:failed', (event) => {
    console.error('Magic link failed:', event.detail.error);
});

Checking Validation Outcome After Page Load

If your code runs after the allegro:magic-link:authenticated or allegro:magic-link:failed events have already fired, read the synchronous magicLinkValidation property instead of listening for events:

// 'authenticated' | 'failed' | null
const result = allegro.magicLinkValidation;

Using the allegro-login-form Component

The <allegro-login-form> web component handles the full magic link flow automatically — no manual SDK calls needed:

<allegro-login-form publisher-name="Example News"></allegro-login-form>

Related

• One-Time Codes guide — passwordless auth via an emailed six-digit code
• Social Login guide — OAuth with Google and Apple
• allegro-login-form component — full UI for magic link + social login