Magic Link

The fastest way to securely enable authentication - passwordless sign-in via email in a couple lines of code.

Introduction

Managing password authentication entails significant overhead for engineering teams and opens up many risks for breaches. Magic Link from WorkOS gives you the ability to build a secure passwordless authentication flow utilizing email. Send users a one-time-use link and let them sign in with a single click.

Magic Link sets you up to handle Single Sign-On via the WorkOS SSO API. The redirect URI / profile retrieval process is identical between Magic Link and SSO.

Magic Link is not a session management solution - instead it is an authentication solution. You as the developer have the ability to manage user sessions as you see fit. This means you determine how long a session is valid for, as well as how to store and invalidate a session.

What you’ll build

In this guide, we’ll take you from learning about passwordless authentication all the way through to building production-ready passwordless authentication flows with the WorkOS Magic Link API.

Sign in to your Developer Dashboard account to see code examples pre-filled with your API keys and resource IDs.

This guide will show you how to:

Before getting started

To get the most out of this guide, you’ll need:

API Object Definitions

ObjectDefinition
Passwordless SessionA Passwordless Session is an object that represents a passwordless authentication session.
ProfileA Profile is an object that represents an authenticated user. The Profile object contains information relevant to a user in the form of normalized and raw attributes.

1
Add Magic Link to your app

Let’s start by building the Magic Link authentication workflow into your app.

1. Install the WorkOS SDK of your choice

WorkOS offers native SDKs in several popular programming languages. Choose a language below to see instructions in your application’s language.

  • Node.jsNode.js
  • RubyRuby
  • GoGo
  • PythonPython
  • PHPPHP
  • LaravelLaravel
  • .NET.NET
Request an SDK

Don't see an SDK you need? Contact us to request an SDK!

Install the SDK using the command below.

Command Line

npm install @workos-inc/node
You can also download the workos-node source code from GitHub.

2. Set environment variables

As a best practice, your WorkOS API key should be kept secret and set as an environment variable on process start. The Project ID should also be set dynamically based on the release environment.

Environment Variables

WORKOS_API_KEY='{secretKey}'
WORKOS_PROJECT_ID='{projectID}'

3. Add a callback endpoint

Let’s first add the redirect endpoint which will handle the callback from WorkOS after a user has authenticated via a magic link. This endpoint should exchange the authorization code (valid for 10 minutes) returned by WorkOS with the authenticated user’s Profile.

The redirect URI must use HTTPS.

Callback Endpoint

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
const express = require('express');
const WorkOS = require('@workos-inc/node');

const app = express();

const workos = new WorkOS(process.env.WORKOS_API_KEY);
const projectID = process.env.WORKOS_PROJECT_ID;

app.get('/callback', async (req, res) => {
  const { code } = req.query;

  const profile = await workos.sso.getProfile({
    code,
    projectID,
  });

  // Use the information in `profile` for further business logic.

  res.redirect('/');
});

4. Create a Passwordless Session and email the user

Create a Passwordless Session to generate an authentication link for a user. An authentication link is valid for 5 minutes and can be sent via the WorkOS API or using your own email service.

You can use the optional state parameter to encode arbitrary information to help restore application state between redirects.

A Magic Link Connection will be automatically created if there isn’t already one for the domain specified when creating a new Passwordless Session.
WorkOS emailCustom email

Use the WorkOS API to send the authentication link to the user. The email sent will be WorkOS branded.

Create a Passwordless Session

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
const express = require('express');
const WorkOS = require('@workos-inc/node');

const app = express();

const workos = new WorkOS(process.env.WORKOS_API_KEY);

app.post('/passwordless-auth', (req, res) => {
  const email =  // ... Email of the user to authenticate

  const session_options = {
    email,
    type: 'MagicLink',
  };
  const session = await workos.passwordless.createSession(session_options);
  await workos.passwordless.sendSession(session.id);

  // Finally, redirect to a "Check your email" page
});

2
Configure a redirect URI

You should set a redirect URI (i.e. the callback endpoint from Add a callback endpoint) via the Developer Dashboard - be sure not to include wildcard subdomains or query parameters.

A Magic Link Connection should be created for every domain, i.e. organization, that wants to authenticate via passwordless authentication. This can be done manually via the Connections Dashboard.

This step is optional. A Magic Link Connection will be automatically created if there isn’t already one for the domain specified when creating a new Passwordless Session.

Go live checklist

Make sure you're ready to go live to production by going through this checklist.

Depending on your network architecture, you may need to allowlist incoming redirect traffic from api.workos.com

WorkOS currently cannot promise that redirect traffic will originate from a static set of IP addresses.