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.
User clicks the link
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:
- Navigate to Console → Authentication → Passwordless
- Toggle Magic Links to enabled
- 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) - Configure Token Expiry — default is 15 minutes. Range: 5–60 minutes
- 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
React
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:
| Scenario | Behavior |
|---|---|
Known email, allowSignup: true | Sends magic link, authenticates existing user |
Unknown email, allowSignup: true | Sends magic link, creates new account on verify |
Unknown email, allowSignup: false | Returns user_not_found error, no email sent |
Known email, allowSignup: false | Sends 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:
| Variable | Description |
|---|---|
{{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
/api/auth/magic-linkSend a magic link email to the provided email address. Body: { email: string }. Respects allowSignup tenant configuration. Rate limited: 5 requests per email per hour.
/api/auth/magic-link/verifyVerify a magic link token and issue access/refresh tokens. Body: { token: string }. The token must not be expired or previously used.
Related Guides
- Hosted Login (PKCE) — The standard interactive login flow
- SMS OTP — Phone-based passwordless authentication
- Passkeys / WebAuthn — Biometric passwordless authentication