Help us shape the future of Go! Take the 2026 Go Developer Survey

magiclink

package
v1.9.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Nov 2, 2026 License: MIT Imports: 19 Imported by: 0

README

Passwordless sign-in over email. The user asks for a link, clicks it, and they are in.

There's no new table for this. Tokens ride on the core verification entity with type="magic_link", so enabling the plugin does not cost you a migration. You supply a Mailer and the plugin handles minting, expiry and single use.

Both endpoints are rate limited, /send against the resend-verification budget and /verify against the verify-email budget, so nobody can use your auth server to bomb an inbox.

Use it when

  • You want signup with as little friction as possible, and no password to reset later
  • Support cost from forgotten passwords is a real line item for you
  • Email is already the identity of record for your users

Skip it when

  • You have no reliable transactional email. This plugin is exactly as available as your mail provider
  • Your users share an inbox, which turns a magic link into a shared credential
  • Sign-in has to work offline or on a device with no mail client. passkey handles that better

Wiring

authsome.WithPlugin(magiclink.New(magiclink.Config{
    Mailer:   myMailer, // implements magiclink.Mailer
    TokenTTL: 10 * time.Minute,
}))

Mailer is required. Without it the plugin has no way to deliver anything.

Config

Field Type Default What it does
Mailer Mailer none Sends the link. Required
TokenTTL time.Duration 10m How long a link stays valid
SessionTokenTTL time.Duration 1h Lifetime of the session the link creates
SessionRefreshTTL time.Duration 30d Lifetime of that session's refresh token

Settings

Key Default
magiclink.token_ttl_seconds 600
magiclink.session_token_ttl_seconds 3600
magiclink.session_refresh_ttl_seconds 2592000

Endpoints

Registered under /v1/magic-link.

Method Path Purpose
POST /send Mint a token and email the link
POST /verify Exchange the token for a session

Lifecycle hooks

None. The plugin is a RouteProvider and a SettingsProvider, and stays out of the core sign-in path.

passkey is the other passwordless option, and it does not depend on your mail provider.

One thing to watch: magiclink.Mailer is its own one-method interface, separate from the engine-wide bridge.Mailer that email and the core flows use. You wire it on this plugin's config, not with authsome.WithMailer.

Documentation

Overview

contract.go: Wires the magiclink plugin into the forge-dashboard contract surface via plugin.ContractContributor.

Package magiclink provides passwordless magic link authentication for AuthSome.

The magic link plugin allows users to sign in by clicking a one-time link sent to their email. It uses the core verification entity (type="magic_link") for token storage, so no additional database tables are required.

Usage: 

mailer := &MyMailer{} // implements magiclink.Mailer
eng, _ := authsome.NewEngine(
    authsome.WithStore(store),
    authsome.WithPlugin(magiclink.New(magiclink.Config{
        Mailer: mailer,
    })),
)

Index

Constants

View Source 
const VerificationTypeMagicLink account.VerificationType = "magic_link"

VerificationTypeMagicLink is the verification type used for magic link tokens.

Variables

View Source 
var (
	// SettingTokenTTLSeconds controls the magic link token lifetime in seconds.
	SettingTokenTTLSeconds = settings.Define("magiclink.token_ttl_seconds", 600,
		settings.WithDisplayName("Token TTL (seconds)"),
		settings.WithDescription("Lifetime of magic link tokens in seconds"),
		settings.WithCategory("Magic Link"),
		settings.WithScopes(settings.ScopeGlobal, settings.ScopeApp),
		settings.WithInputType(formconfig.FieldNumber),
		settings.WithUIValidation(formconfig.Validation{Required: true, Min: intPtr(60), Max: intPtr(3600)}),
		settings.WithHelpText("How long magic link tokens remain valid. Default: 600 (10 minutes)"),
		settings.WithOrder(10),
	)

	// SettingSessionTokenTTLSeconds controls the session token lifetime for magic link sessions.
	SettingSessionTokenTTLSeconds = settings.Define("magiclink.session_token_ttl_seconds", 3600,
		settings.WithDisplayName("Session Token TTL (seconds)"),
		settings.WithDescription("Lifetime of sessions created via magic link in seconds"),
		settings.WithCategory("Magic Link"),
		settings.WithScopes(settings.ScopeGlobal, settings.ScopeApp),
		settings.WithInputType(formconfig.FieldNumber),
		settings.WithUIValidation(formconfig.Validation{Required: true, Min: intPtr(300), Max: intPtr(86400)}),
		settings.WithHelpText("How long sessions created via magic link remain valid. Default: 3600 (1 hour)"),
		settings.WithOrder(20),
	)

	// SettingSessionRefreshTTLSeconds controls the refresh token lifetime for magic link sessions.
	SettingSessionRefreshTTLSeconds = settings.Define("magiclink.session_refresh_ttl_seconds", 2592000,
		settings.WithDisplayName("Refresh Token TTL (seconds)"),
		settings.WithDescription("Lifetime of refresh tokens for magic link sessions in seconds"),
		settings.WithCategory("Magic Link"),
		settings.WithScopes(settings.ScopeGlobal, settings.ScopeApp),
		settings.WithInputType(formconfig.FieldNumber),
		settings.WithUIValidation(formconfig.Validation{Required: true, Min: intPtr(3600), Max: intPtr(7776000)}),
		settings.WithHelpText("How long refresh tokens remain valid. Default: 2592000 (30 days)"),
		settings.WithOrder(30),
	)
)

Functions

This section is empty.

Types

type Config 

type Config struct {
	// Mailer sends magic link emails. Required.
	Mailer Mailer

	// TokenTTL is the lifetime of magic link tokens (default: 10 minutes).
	TokenTTL time.Duration

	// SessionTokenTTL is the lifetime of sessions created via magic link (default: 1 hour).
	SessionTokenTTL time.Duration

	// SessionRefreshTTL is the lifetime of refresh tokens for magic link sessions (default: 30 days).
	SessionRefreshTTL time.Duration
}

Config configures the magic link plugin.

type Mailer added in v1.9.0 

type Mailer interface {
	SendMagicLink(ctx context.Context, email, token string) error
}

Mailer sends magic link emails.

type MailerFunc added in v1.9.0 

type MailerFunc func(ctx context.Context, email, token string) error

MailerFunc is an adapter to use a plain function as a Mailer. 

func (f MailerFunc) SendMagicLink(ctx context.Context, email, token string) error

SendMagicLink implements Mailer.

type Plugin 

type Plugin struct {
	// contains filtered or unexported fields
}

Plugin is the magic link authentication plugin.

func New added in v1.9.0 

func New(cfg ...Config) *Plugin

New creates a new magic link plugin.

func (*Plugin) DeclareSettings added in v1.9.0 

func (p *Plugin) DeclareSettings(m *settings.Manager) error

DeclareSettings implements plugin.SettingsProvider.

func (*Plugin) Name added in v1.9.0 

func (p *Plugin) Name() string

Name returns the plugin name.

func (*Plugin) OnInit added in v1.9.0 

func (p *Plugin) OnInit(_ context.Context, engine plugin.Engine) error

OnInit captures the store reference from the engine.

func (*Plugin) RegisterContract added in v1.9.0 

func (p *Plugin) RegisterContract(
	d *dispatcher.Dispatcher,
	reg contract.Registry,
	wreg contract.WardenRegistry,
	engine plugin.Engine,
) error

func (*Plugin) RegisterRoutes 

func (p *Plugin) RegisterRoutes(router forge.Router) error

RegisterRoutes registers magic link HTTP endpoints on a forge.Router.

func (*Plugin) SetAppID added in v1.9.0 

func (p *Plugin) SetAppID(appID string)

SetAppID sets the app ID for the plugin (used in testing).

func (*Plugin) SetStore added in v1.9.0 

func (p *Plugin) SetStore(s store.Store)

SetStore allows direct store injection for testing.

type SendRequest 

type SendRequest struct {
	Email string `json:"email"`
	AppID string `json:"app_id,omitempty"`
}

SendRequest is the request body for sending a magic link.

type SendResponse 

type SendResponse struct {
	Status string `json:"status"`
}

SendResponse is returned when a magic link is sent.

type VerifyRequest added in v1.9.0 

type VerifyRequest struct {
	Token string `json:"token"`
	AppID string `json:"app_id,omitempty"`
}

VerifyRequest is the request body for verifying a magic link.

type VerifyResponse 

type VerifyResponse struct {
	User         any    `json:"user"`
	SessionToken string `json:"session_token"`
	RefreshToken string `json:"refresh_token"`
	ExpiresAt    any    `json:"expires_at"`
}

VerifyResponse is returned when a magic link is verified.

Source Files

View all Source files

Directories

Path Synopsis
Package contract wires the magiclink plugin's deep-link settings page into the forge-dashboard contract registry.
 Package contract wires the magiclink plugin's deep-link settings page into the forge-dashboard contract registry.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.