# Magic Links

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

## How It Works[​](#how-it-works "Direct link to 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[​](#requesting-a-magic-link "Direct link to Requesting a Magic Link")

```js
await allegro.member.requestMagicLink(
    'user@example.com',
    '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                                                |

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[​](#validating-a-token-manually "Direct link to Validating a Token Manually")

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

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

```

## SDK Events[​](#sdk-events "Direct link to 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)            |

```js
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[​](#checking-validation-outcome-after-page-load "Direct link to 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:

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

```

## Using the allegro-login-form Component[​](#using-the-allegro-login-form-component "Direct link to Using the allegro-login-form Component")

The [`<allegro-login-form>`](/developer/components/login-form.md) web component handles the full magic link flow automatically — no manual SDK calls needed:

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

```

## Related[​](#related "Direct link to Related")

* [Social Login guide](/developer/guides/authentication/social-login.md) — OAuth with Google and Apple
* [allegro-login-form component](/developer/components/login-form.md) — full UI for magic link + social login