Skip to Content
GuidesAuthenticationMagic Links

Magic Links (Passwordless Email)

Magic links provide a passwordless authentication experience: the user enters their email address, receives a sign-in link, and clicks it to authenticate — no password required. Auris handles token generation, email delivery, and verification.

Magic links are suitable as a standalone login method or as a secondary option alongside email/password on the hosted login page.


How It Works

User submits their email

Your application sends the user’s email address to the Auris magic link endpoint. Auris generates a cryptographically random single-use token, stores a SHA-256 hash of it, and composes the sign-in link.

Auris sends the email

Auris delivers the magic link email using the SMTP configuration on your tenant. The link points to the redirect URL configured in Console → Authentication → Passwordless, with the token appended as a query parameter.

The user’s email client opens the link. The page at your redirect URL extracts the token from the URL and calls the Auris verification endpoint.

Auris verifies the token

Auris validates the token: it must exist, not be expired, and not have been used before. On success, Auris issues an access token and refresh token.

Auto-signup for new emails

If allowSignup: true is configured and the email does not exist in Auris, a new user account is created automatically at verification time. The user is authenticated into the new account immediately.


Console Configuration

Before using magic links, configure the feature in the Auris Console:

  1. Navigate to ConsoleAuthenticationPasswordless
  2. Toggle Magic Links to enabled
  3. Set the Redirect URL — the page in your application that will receive the token and call the verify endpoint (e.g., http://localhost:3000/auth/magic-link/verify)
  4. Configure Token Expiry — default is 15 minutes. Range: 5–60 minutes
  5. Set Allow Signup — when enabled, clicking a magic link with an unknown email creates a new account

The redirect URL must be registered in your application’s allowed callback URLs. Auris rejects magic link redirects to unregistered URLs.


Implementation

import { useState } from 'react' import { useAuris } from '@auris/react' import { useSearchParams, useNavigate } from 'react-router-dom' // Send magic link form function MagicLinkForm() { const { loginWithMagicLink } = useAuris() const [email, setEmail] = useState('') const [sent, setSent] = useState(false) const [error, setError] = useState(null) async function handleSubmit(e) { e.preventDefault() const result = await loginWithMagicLink(email) if (result.success) { setSent(true) } else { setError(result.error) } } if (sent) { return ( <div> <h2>Check your email</h2> <p>We sent a sign-in link to {email}. The link expires in 15 minutes.</p> </div> ) } return ( <form onSubmit={handleSubmit}> <label>Email address</label> <input type="email" value={email} onChange={(e) => setEmail(e.target.value)} required /> {error && <p className="error">{error}</p>} <button type="submit">Send sign-in link</button> </form> ) } // Verification page — receives the token from the email link function MagicLinkVerifyPage() { const { verifyMagicLink } = useAuris() const [searchParams] = useSearchParams() const navigate = useNavigate() useEffect(() => { const token = searchParams.get('token') if (!token) { navigate('/login?error=missing_token') return } verifyMagicLink(token).then((result) => { if (result.user) { navigate('/dashboard') } else { navigate('/login?error=invalid_token') } }) }, []) return <p>Verifying your sign-in link...</p> }

Auto-signup Behavior

When allowSignup: true is configured in the Console, the magic link flow supports creating new user accounts:

ScenarioBehavior
Known email, allowSignup: trueSends magic link, authenticates existing user
Unknown email, allowSignup: trueSends magic link, creates new account on verify
Unknown email, allowSignup: falseReturns user_not_found error, no email sent
Known email, allowSignup: falseSends magic link, authenticates existing user

When a new account is created via auto-signup, it has no password set. The user can add a password later through the account settings, or continue using magic links indefinitely.


Email Template Customization

The magic link email uses the Passwordless Login template in Console → Authentication → Email Templates. The template supports the following variables:

VariableDescription
{{magic_link}}The full sign-in URL including the token
{{user_email}}The recipient’s email address
{{expires_in}}Human-readable expiry duration (e.g., “15 minutes”)
{{tenant_name}}Your tenant’s display name
{{app_name}}The application name requesting the login

Security Considerations

Single-use tokens — Each magic link token can only be used once. Clicking an already-used link returns a token_already_used error.

Token expiry — Tokens expire after the configured duration (default: 15 minutes). Expired tokens return a token_expired error with a prompt to request a new link.

Token hashing — Auris stores only the SHA-256 hash of the token. The raw token is only ever present in the email and the URL — never stored in plaintext in the database.

Rate limiting — Auris applies rate limits to the magic link send endpoint: a maximum of 5 link requests per email address per hour. This prevents email flooding abuse.

No password required — Magic links are suitable for user populations where passwords are friction. They are not weaker than passwords when token expiry and single-use constraints are enforced.


API Endpoints

POST/api/auth/magic-link

Send a magic link email to the provided email address. Body: { email: string }. Respects allowSignup tenant configuration. Rate limited: 5 requests per email per hour.

POST/api/auth/magic-link/verify

Verify a magic link token and issue access/refresh tokens. Body: { token: string }. The token must not be expired or previously used.