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) | Backward-compatible camelCase alias for organization context |
| data.org_slug | string (optional) | Organization slug for tenant-scoped magic-link login |
| data.service_slug | string (optional) | Service slug for service-scoped magic-link login |
| data.redirect_uri | string (optional) | Service callback URI preserved through verification |
Returns: Promise<MagicLinkResponse> - Confirmation message.
Example:
const response = await sso.magicLinks.request({
email: 'user@example.com',
org_slug: 'acme-corp',
service_slug: 'main-app',
redirect_uri: 'https://app.acme.com/callback'
});
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;
org_slug?: string;
orgSlug?: string;
service_slug?: string;
redirect_uri?: string;
}
MagicLinkResponse
interface MagicLinkResponse {
message: string;
}