Magic Link

Strapi 5 plugin · Node.js 22 to 26 · MIT

Passwordless sign-in for Strapi 5

Your users type their e-mail address, click the link and get a normal Users & Permissions session. When a link is not enough, add an e-mailed one-time code (OTP) or an authenticator app (TOTP) with backup codes.

Install in one minute See the API

  • Free and open source
  • No telemetry
  • Works with several instances
  • 5 admin languages
Magic Link token management in the Strapi admin: status cards for total, active, expired, used and blocked links above a searchable token table

Features

Passwordless authentication by e-mail, optional second factors, and an admin panel for tokens, sessions and IP bans. Every feature ships in the npm package; there is no key to unlock anything.

  1. Request

    Your app calls POST /send-link with an e-mail address.

  2. Click

    The user opens the link; your landing page posts the token to Strapi.

  3. Session

    Strapi answers with a JWT, or first asks for an OTP or TOTP code.

Magic links by e-mail

Hashed, expiring, single-use links sent through your Strapi e-mail provider, Magic Mail or Email Designer 5. The request never reveals whether an account exists.

E-mail OTP

Ask for a one-time code from a second e-mail after the link click. Attempts are limited and counted atomically.

TOTP and MFA

Optional or required authenticator apps. Users enrol during sign-in or later from their account, and get ten one-time backup codes.

Native sessions

Works with Users & Permissions in legacy JWT mode and in refresh mode, where logins return a refresh token like /api/auth/local.

Context and delivery status

Pass a small context such as redirectTo through the link. Each e-mailed link shows whether the provider accepted, rejected or bounced it.

Admin panel

Tokens, OTP codes, JWT sessions, IP bans and settings, in five languages, light and dark mode, with permissions enforced on the server.

Install

Requires Strapi 5.24 or newer (acceptance host: 5.62.0), Node.js 22 to 26 and a configured Strapi e-mail provider. npm, yarn and pnpm install it without peer warnings.

One minute, in your Strapi project
npm install strapi-plugin-magic-link-v5
echo "MAGIC_LINK_ENCRYPTION_KEY=$(node -e "console.log(require('crypto').randomBytes(32).toString('hex'))")" >> .env
echo "MAGIC_LINK_OTP_PEPPER=$(node -e "console.log(require('crypto').randomBytes(32).toString('hex'))")" >> .env
npm run build && npm run develop
  1. The plugin refuses to start without the two secrets (32 or more characters each). For a throwaway local setup, MAGIC_LINK_ALLOW_DEV_SECRETS=true works outside production.

  2. In Settings → Magic Link → Settings → General, set the frontend base URL and login path of your landing page.

  3. Send the first link.

    curl -X POST http://localhost:1337/api/magic-link/send-link \
      -H 'Content-Type: application/json' \
      -d '{"email":"ada@example.com"}'
    # { "email": "ada@example.com", "username": null, "sent": true, "delivery": "email" }

The answer is the same whether or not the account exists. By default only existing users get a link; auto-registration is a setting.

Configuration

Most options live in Settings → Magic Link → Settings: link lifetime and length, where links point, sender and templates, auto-registration, rate limits and the sign-in mode. The README lists every key with its default.

Sign-in modes
Mode Setting After the link click
Link only default The user is signed in
Link + e-mail OTP otp_enabled A code from a second e-mail
Link + TOTP (optional MFA) mfa_mode: optional A code from the app if the user enrolled
Link + TOTP (required MFA) mfa_mode: required A code from the app; enrolment on the spot if needed
TOTP only totp_as_primary_auth No e-mail: POST /login-totp
Settings you will touch first
Key Default Meaning
frontend_url, frontend_login_path empty, /auth/magic-link Your landing page (https; http only for localhost)
expire_period 3600 Link lifetime in seconds
stays_valid false Allow a link to be used more than once until it expires
jwt_token_expires_in 30d JWT lifetime in legacy mode
rate_limit_max_attempts, rate_limit_window_minutes 5, 15 Requests per IP and per address in the window
createUserIfNotExists + allow_magic_links_on_public_registration true, false Create accounts on first login (also needs users-permissions sign-ups)
Server config (config/plugins.js, all optional)
Key Default Effect
allowedLinkOrigins [] Login links may only point at these origins; admins cannot change the list
rateLimit.redis off Redis fast path for rate limits; the database stays the fallback
rateLimit.store database 'memory' keeps counters per process (single process only)
deliveryWebhooks {} Bounce and complaint feedback from SendGrid, Mailgun, SES or Postmark
Environment variables
Variable Required Purpose
MAGIC_LINK_ENCRYPTION_KEY yes AES-256-GCM key for TOTP secrets, 32+ characters
MAGIC_LINK_OTP_PEPPER yes Key for OTP code hashes and backup-code HMACs, 32+ characters
MAGIC_LINK_ENCRYPTION_KEY_PREVIOUS no Old key during rotation; secrets are re-encrypted at startup
MAGIC_LINK_ALLOW_DEV_SECRETS no true allows derived development secrets outside production

E-mail templates use placeholders such as {{LOGIN_URL}}, {{EXPIRY_TEXT}} and {{USER}}. Values are HTML-escaped and no template code runs.

Behind a reverse proxy, set proxy: { koa: true, maxIpsCount: 1 } in config/server.js so rate limits and IP bans see the real client address.

Permissions

Grant these in Settings → Administration Panel → Roles → Plugins → Magic Link. The server checks them on every admin route; the admin pages only hide what a role cannot do.

Admin actions
Action Grants
plugin::magic-link.read Menu entry and Tokens page: tokens, OTP codes, JWT sessions, IP bans
plugin::magic-link.manage Create, block, extend and delete tokens; revoke sessions; ban IPs; cleanups
plugin::magic-link.tokens.issue Create a link without e-mail (impersonation). Grant sparingly.
plugin::magic-link.settings.read Settings page, rate-limit statistics, MFA summary
plugin::magic-link.settings.update Save settings, rate-limit cleanup and reset
plugin::magic-link.settings.security Link targets, templates, sender, account, MFA, code and rate-limit rules

Users & Permissions: the login routes are public by design and protected by rate limits and IP bans. Grant the Magic-link → totp actions to the Authenticated role if users should manage their authenticator themselves.

Security

What is protected, and how.

Login links

At least 132 bits, stored salted and hashed, expiring. A single-use link is consumed with a conditional update, so parallel clicks give one session.

No account discovery

send-link answers before any lookup or delivery, with the same body and timing for every address.

Second factors

Challenge state lives on the server. OTP attempts are counted before the comparison, TOTP codes cannot be replayed, and code checks are limited to 10 per account and 15 minutes even with rate limiting off.

Sessions

Revoked JWTs stay blocked until they expire. In refresh mode a revocation ends the whole users-permissions refresh family, rotated tokens included.

Pre-account hijacking

Confirming an unconfirmed account by link, OTP or enrolment first ends its sessions and clears a password someone else may have set.

Admin permissions

Every admin route checks a permission on the server. Impersonation (tokens.issue) and settings that redirect links (settings.security) have their own permissions.

Known limit: MFA covers the Magic Link login paths only. Password or social logins through Users & Permissions do not ask for a second factor, so disable the ones you do not use.

Report vulnerabilities privately through GitHub security advisories.

Privacy and outbound connections

No telemetry, no usage statistics, no update check and no registration server. The plugin sends nothing about your installation anywhere.

What leaves your server, only because you configured it
Connection When
Your e-mail provider or Magic Mail A link, an OTP code or a TOTP setup code is e-mailed
sns.<region>.amazonaws.com Only with the SES bounce webhook: the SNS signing certificate and the subscription confirmation
Redis Only with rateLimit.redis

Everything else stays in your Strapi database: login tokens as salted hashes (deleted 30 days after expiry), OTP codes as keyed hashes, TOTP secrets encrypted with AES-256-GCM, one record per issued JWT (kept until 7 days after expiry) and rate-limit counters. Plugin logs contain no e-mail addresses, tokens or login URLs.

Performance

Logins do not queue

A login inserts one session row without a lock. With 4 Strapi processes on PostgreSQL 16, 100 simultaneous link clicks finished in 0.38 s.

Cheap revocation checks

Each process caches the JWT blocklist for 2 seconds, so a Content API request normally costs no extra query.

Shared rate limits

One row per key in magic_link_rate_limits. Redis is an optional fast path; the database stays its fallback.

Housekeeping off the request path

Expired codes, old tokens, session records and limiter rows are removed every 5 minutes by one process at a time.

Running several instances (Railway replicas, pm2 cluster)

Magic Link works with any number of Strapi processes on one shared database, for example 2 Railway replicas with 4 pm2 cluster workers each. Requests may land on any process; sticky sessions are not needed and Redis is optional.

  1. One database for all processes. PostgreSQL (recommended) or MySQL/MariaDB. SQLite works for several processes on one machine and file, not across machines.

  2. The same secrets everywhere: Strapi's APP_KEYS, API_TOKEN_SALT, ADMIN_JWT_SECRET, JWT_SECRET, TRANSFER_TOKEN_SALT, ENCRYPTION_KEY, plus MAGIC_LINK_ENCRYPTION_KEY and MAGIC_LINK_OTP_PEPPER.

  3. The real client IP. Behind Railway's edge proxy, set proxy: { koa: true, maxIpsCount: 1 } in config/server.js.

  4. Start the processes. On Railway, set the replica count in the service's scaling settings. For pm2 cluster mode:

    ecosystem.config.js
    module.exports = {
      apps: [
        {
          name: 'strapi',
          // Cluster mode needs a Node.js script, not `npm start`.
          script: './node_modules/@strapi/strapi/bin/strapi.js',
          args: 'start',
          instances: 4, // or 'max'
          exec_mode: 'cluster',
          env: { NODE_ENV: 'production' },
        },
      ],
    };

    Start it with pm2 start ecosystem.config.js. Inside a Railway container, add pm2 to the project and use pm2-runtime start ecosystem.config.js as the start command.

  5. Plugin config: nothing is required. Do not set rateLimit: { store: 'memory' } with several processes, or every limit is multiplied by the number of processes.

What is shared, and how
State Mechanism
Login links, OTP codes, TOTP replay, backup codes Conditional database updates: accepted exactly once across processes
JWT blocklist, IP bans, settings Written under a cluster-wide lock: PostgreSQL pg_advisory_xact_lock, MySQL GET_LOCK, SQLite's write lock
JWT session records One row per JWT in magic_link_jwt_sessions, inserted without a lock
Rate limits Table magic_link_rate_limits, or Redis with the database as fallback
New accounts, account claims, challenge starts Locks and compare-and-set, so one address never gets two accounts
Cleanup jobs and startup migrations One process at a time (a lease or the cluster lock)

Short windows: a revocation reaches other processes within 2 seconds, changed rate limits within 5 seconds. When several processes start at once on an empty database or after a schema change, all but one may stop once with relation ... already exists; the restarted process starts normally (pm2 and Railway's on-failure policy restart it). Tested with 8 processes against SQLite and PostgreSQL 16 (npm run test:cluster).

API

Public routes are mounted under /api/magic-link. Your landing page receives ?loginToken= and exchanges it with a POST, so the token stays out of access logs and Referer headers.

Landing page
const loginToken = new URLSearchParams(location.search).get('loginToken');
const res = await fetch('https://api.example.com/api/magic-link/login', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ loginToken }),
});
const result = await res.json();
// result.jwt, or result.requiresOTP / requiresTOTP / requiresTOTPSetup
Public routes
Method Path Purpose
POST /send-link Send a magic link to { email, context? }
POST /login Exchange { loginToken } (GET kept for compatibility)
POST /otp/send, /otp/resend, /otp/verify E-mail OTP step
POST /verify-mfa-totp TOTP or backup code after the link
POST /totp/enroll, /totp/enroll/confirm Enrol an authenticator during a required-MFA login
GET, POST /totp/status, /totp/setup, /totp/confirm, /totp/disable, /totp/backup-codes Self-service for signed-in users (Authenticated role)
POST /login-totp TOTP-only login
POST /delivery-webhooks/:provider Signed bounce and complaint feedback (off until a secret is set)

Errors use the Strapi envelope with a stable error.key, for example token.invalid, mfa.invalidCode or rate.limit.exceeded (with details.retryAfter). Messages are translated into English, German, French, Spanish and Portuguese.

With jwtManagement: 'refresh' in Users & Permissions, logins return a short-lived JWT and a refresh token; renew with the native POST /api/auth/refresh. Admin routes live under /magic-link and need an admin JWT plus the permission from the table above. The README lists every route with request and response examples and all error answers.

FAQ

Does it replace the Strapi admin login?

No. Magic Link signs in the users of your app (Users & Permissions accounts). The Strapi admin login stays as it is.

Do I need a frontend?

For a good experience, yes: a form that calls send-link and a landing page that posts the token to /login. Any framework works.

Can new users sign up with a link?

Yes, when createUserIfNotExists, allow_magic_links_on_public_registration and the users-permissions sign-ups are all on.

Does it work with GraphQL?

The login routes are REST. The JWT they return works for GraphQL like any users-permissions JWT, and revoked tokens are rejected there too.

Is there a paid version or a key to unlock features?

No. Every feature is in the npm package. 7.0.0 removed the old optional key field and deletes a stored key on its first start.

Can I keep password login?

Yes. /api/auth/local keeps working; the Magic Link MFA settings only apply to Magic Link logins.

Releases and compatibility

7.0.0 removes the optional registration key, its admin page and its two admin routes. Logins, second factors, sessions, context and delivery status are unchanged, and the first start deletes a stored key. Upgrading from 5.x? Work through the 6.0.0 guide first: new secrets, admin permissions, the POST token exchange and template placeholders.

Compatibility
Magic Link Strapi Node.js
7.x 5.24.0 or newer (acceptance host: 5.62.0) 22 to 26
6.x 5.24.0 or newer 22 to 26
5.x 5.0.0 or newer 18 to 22

Releases use semantic-release and Conventional Commits and are published to npm with trusted publishing and provenance. Dependabot proposes weekly updates; patch and minor updates merge after lint, tests, build and verify pass. Run the same checks locally:

npm ci --legacy-peer-deps
npm run lint && npm run format:check && npm test
npm run build && npm run verify