Magic Link Plugin

The Magic Link plugin provides passwordless authentication using email-based magic links. Users receive a secure link via email that they can click to sign in without passwords.

Features

Passwordless authentication via email
Secure token-based verification
Configurable expiration time
Optional user registration on first sign-in
Custom email sending function support

Standalone Mode

In standalone mode, configure the plugin in your config.toml:

[plugins.magic_link]
enabled = true
expires_in = "15m"  # Token expiration time
disable_sign_up = false  # Allow new user registration

Library Mode

Embed the plugin in your Go application:

import (
  authula "github.com/Authula/authula"
  authulaconfig "github.com/Authula/authula/config"
  authulamodels "github.com/Authula/authula/models"
  magiclinkplugin "github.com/Authula/authula/plugins/magic-link"
  magiclinkplugintypes "github.com/Authula/authula/plugins/magic-link/types"
)

config := authulaconfig.NewConfig(/*...*/)
auth := authula.New(authula.AuthConfig{
  Config: config,
  Plugins: []authulamodels.Plugin{
    magiclinkplugin.New(magiclinkplugintypes.MagicLinkPluginConfig{
      Enabled: true,
      ExpiresIn: 15 * time.Minute,
      DisableSignUp: false,
      // Optional: Custom email sender function
      // SendMagicLinkVerificationEmail func(email string, url string, token string) error {
      //   // Implement your email sending logic here, e.g. using an email service provider
      //   return nil
      // }
    }),
  },
})

API Endpoints

Sends a magic link email to the user.

POST /magic-link/sign-in

Request body:

{
  "email": "user@example.com",
  "name": "John Doe", // optional
  "callback_url": "https://yourapp.com/callback" // optional
}

Verify

Verifies the token from the email link. If callback_url is provided, redirects with the token. Otherwise returns the token in JSON.

GET /magic-link/verify?token=<token>&callback_url=<url>

Exchange

POST /magic-link/exchange

Request body:

{
  "token": "<verification_token>"
}

Exchanges the verified token for user session and authentication.

Usage Flow

Client calls /magic-link/sign-in with user's email
User receives email with link containing verification token
User clicks link, which calls /magic-link/verify and the token is verified
Client then receives another token to exchange with a session by calling /magic-link/exchange
User is now signed in with session established

Client Plugin

If you're using the Authula SDK. Add the plugin to the SDK like so:

import { createClient } from "authula";
import { MagicLinkPlugin } from "authula/plugins";

export const authulaClient = createClient({
  url: "http://localhost:8080/auth",
  plugins: [
    // other plugins...
    new MagicLinkPlugin(),
  ],
});

Magic Link Plugin

On this page