Magic Links Module

The magic links module (sso.magicLinks) enables passwordless authentication via email links.

Methods

`sso.magicLinks.request()`

Signature:

request(data: MagicLinkRequest): Promise<MagicLinkResponse>

Description: Request a magic link to be sent to the user’s email address. The email contains a one-time login link that authenticates the user when clicked.

Parameters:

Name	Type	Description
data	MagicLinkRequest	Magic link request payload
data.email	string	Email address to send the magic link to
data.orgSlug	string (optional)	Organization context for the login

Returns: Promise<MagicLinkResponse> - Confirmation message.

Example:

const response = await sso.magicLinks.request({
  email: 'user@example.com',
  orgSlug: 'acme-corp'
});
console.log(response.message); // "Magic link sent to your email"

`sso.magicLinks.verify()`

Signature:

verify(token: string, redirectUri?: string): Promise<any>

Description: Verify a magic link token and complete authentication. This method exchanges the token for a JWT session. Use this when handling magic link verification via API call rather than browser redirect.

Parameters:

Name	Type	Description
token	string	The magic link token from the email
redirectUri	string (optional)	Optional redirect URI after successful verification

Returns: Promise<any> - Authentication response with tokens.

Example:

// Extract token from URL query parameter
const urlParams = new URLSearchParams(window.location.search);
const token = urlParams.get('token');

if (token) {
  const auth = await sso.magicLinks.verify(token);
  sso.setAuthToken(auth.access_token);
  localStorage.setItem('sso_access_token', auth.access_token);
}

`sso.magicLinks.getVerificationUrl()`

Signature:

getVerificationUrl(token: string, redirectUri?: string): string

Description: Construct the verification URL for a magic link token. This is typically used when you need to generate the URL that would be sent in the email.

Parameters:

Name	Type	Description
token	string	The magic link token
redirectUri	string (optional)	Optional redirect URI after successful verification

Returns: string - The verification URL path.

Example:

const verifyUrl = sso.magicLinks.getVerificationUrl('token-abc123', 'https://app.acme.com/dashboard');
console.log('Verification URL:', verifyUrl);
// "/api/auth/magic-link/verify?token=token-abc123&redirect_uri=https://app.acme.com/dashboard"

Type Definitions

MagicLinkRequest

interface MagicLinkRequest {
  email: string;
  orgSlug?: string;
}

MagicLinkResponse

interface MagicLinkResponse {
  message: string;
}