 (launched last week), we realized that our session management solution should be launched and marketed as a standalone product.

Our key insight was that developers use "authentication" to refer to two distinct concepts:

User authentication - when a user verifies their identity to sign-in

Session authentication - when an application's backend determines which user is making a request

Clerk has always offered both, but the session side of our offering used to be hidden in the background.

Our launch today brings many improvements to our session management offering, and in parallel, begins highlighting the advantages separately.  The key advantages are:

Allowing multiple users to be signed in simultaneously on a single device

Soon, we plan to completely decouple session management from our user management product.  This is meant for developers who already have a user management solution, but are looking for one (or all) of the key advantages above.

Several developers have asked if they can add more sections to our 

 to make the component more easily extensible, including an option to hide our default navigation bar so developers can build their own with extra sections.

We've added support for social sign-in with Discord and GitLab.  Twitter is now under development!

New Guide: Syncing user data to your backend

Most of our customers do not need to sync user data to their own backend, but a few still need to.  We've added a guide for 

Changelog Nov 5, 2021

 components. But since launching our B2B SaaS Suite for onboarding business customers, our top feature request has become better 

 capabilities: not just helping developers determine 

 a user is, but also what permissions they have within their organization.

Today we’ve launched two new features to make robust authorization easy:

In Clerk’s dashboard, developers can now define custom roles, which their business customers can assign to their employees. Previously, roles were restricted to just “admin” and “member.”

In addition, fine-grained permissions can now be defined and mapped to roles. When used properly, this extra layer of abstraction allows developers to create additional roles as-needed, without making any changes to their codebase.

Each role and permission defined in Clerk’s dashboard has a corresponding key, like 

To make it easy to leverage permissions for authorization checks, we’ve introduced three new helpers in our SDKs.

 function on both the frontend and the backend to determine if the active user “has” a particular role or permission.

 can be used anywhere that Clerk returns an “auth” object:

 in client components, including during SSR

 in server contexts outside of the App Router (Remix Loaders, Node, Express, Fastify, etc)

, which takes definitive action to block further processing, instead of allowing developers to manually handle the unauthorized case. It is intended to be used in cases where unauthorized users are assumed to be attackers.

Consider an endpoint that your product would never issue a request to unless the current user is authorized. For example, you may have a page with a button that can issue requests to that endpoint, but the page is only accessible to authorized users. That is the perfect place to use 

 – you don't need a precisely-written error, just confidence that an attacker's requests will fail.

 has launched in Next.js only, though we will extend the helper to other frameworks in the future. Please use 

 to request the feature for your framework.

 component is intended to block further processing. It only renders children for authorized users, and optionally renders a 

 can be used across all React frameworks, in CSR, SSR, and RSC contexts.

For full details and usage information, please see our updated Organization documentation, including:

Authorization is now a core feature of Clerk

With today’s launch, authorization has become a core feature of Clerk, and you will see significant, continued investment in the future.

In 2024, we will extend our authorization helpers to support entitlements, so Clerk can be used to gate features based on the subscription plan a customer selected.

Further, you likely noticed above that every role and permission is namespaced with the 

 prefix, which relates to the Organization resource. We recognize this is limiting, and in the future we will be extending our authorization helpers to work with other resources.

Introducing has(), protect(), and <Protect>

Data breaches and password overload have made companies and their users wary of using a traditional username/password authentication system. Companies know that handling user passwords is both technically challenging 

 costly, as it requires stringent security measures, robust infrastructure for storage, and continuous monitoring to prevent unauthorized access. Users find it cumbersome to manage multiple complex passwords for various accounts, especially with the prevalence of methods like SSO, and often end up reusing passwords across different platforms, as a matter of convenience; this not only leaves the individual vulnerable, but also makes companies jobs of securing data that much harder.

Luckily, magic links have emerged as an elegant solution to secure user sessions in a 

 context. Their rising popularity is underpinned by their dual advantages:

An augmented security posture through the minimization of phishing opportunities and password theft.

An optimized user experience devoid of the need to memorize and manage many login credentials.

Magic links are a token-based authentication (TBA) strategy that uses a unique, time-sensitive URL, which leverages a securely-generated token to serve as a credential for user authentication.

The links are sent directly to the user's registered email or phone number, providing a straightforward, secure authentication method. When a user clicks on a magic link, the embedded token is validated against the server to authenticate the user's identity. This process, by design, eliminates the traditional risks associated with password-based systems and simplifies the login experience for the user.

In this guide, we will show you why you should consider magic links and how they work at a high level, before going through a Next.js App Router implementation to show how you can add magic links to your application.

Magic links bolster the security architecture of authentication systems by adopting a token-based, stateless interaction model. Each link is cryptographically unique and typically accompanied by an expiration timestamp, making it resilient against replay attacks. Given their ephemeral nature, even if a magic link were to be intercepted or exposed, its short-lived validity constrains the window of opportunity for malicious exploitation.

But there are a few other benefits to magic links for companies and users:

. Magic links eliminate the cognitive burden of remembering and managing many complex passwords, by providing a single-click authentication pathway. This frictionless access modality can enhance user engagement and satisfaction, reducing abandonment rates during the sign-in or sign-up processes.

. By using magic links to minimize passwords, organizations can reduce the risk of breaches involving personal data and avoid the consequences of compromised credentials, which can include heavy fines and reputational damage.

. With magic links, the threat of credential stuffing attacks—where compromised credentials are used to gain unauthorized access to multiple user accounts—is mitigated. Since magic links do not rely on reusable passwords, the standard vector of credential exposure is eliminated, enhancing overall system security.

. For users with disabilities or those less familiar with technology, magic links offer a more accessible authentication mode. The simplification of the login process—replacing typing and memory demands with a single action—can be particularly advantageous for individuals facing physical or cognitive challenges.

A magic link is structurally composed of two critical elements: the URL, which provides the link for the user's web interaction, and the embedded token, a cryptographically-generated string serving as the temporary credential.

In essence, a typical magic link may resemble the following structure:

https://example.com/authenticate?token=a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6

 query parameter carries the weight of authentication, substantiating the user's claim without revealing identity until verified by the server.

Here’s an example of how the process works:

Magic links are designed to become invalid under certain conditions for security purposes:

: The token embedded in the link has a short lifespan and is often configurable based on application security requirements.

: Once a magic link is used, it becomes invalid, preventing multiple uses, which could lead to unauthorized access.

: The system can programmatically revoke a token, thus invalidating the magic link in response to specific triggers or anomalies.

The lifecycle of a magic link commences with the generation of a unique token. This process employs cryptographic algorithms to ensure each token is a random, high-entropy string, making it virtually impossible to predict or reproduce through brute force or other cryptographic attacks. Typically, the token generation utilizes 

 to guarantee the robustness of the token against collision and preimage attacks.

Once generated, the token is stored on the server along with metadata that includes the user's identifier, the token's expiration time, and any other relevant session data. The magic link is then composed by appending the token to a predetermined URL structure, forming a complete, ready-to-use hyperlink.

This link is dispatched to the user's email address or phone number via SMTP or SMS protocols. The communication channel must be secure, leveraging TLS for email and similarly secure protocols for SMS to safeguard the link during transit.

pically interacts with the magic link by clicking on it, which initiates a secure request to the service's endpoint. The service extracts the token from the URL and verifies it against the stored data. This verification process involves several checks:

: Validates that the token matches a recently generated and stored token.

: Ensures the token has not been tampered with during transit.

: Confirms the token has not expired based on the predefined validity period.

: Ensures the token has not been used before, adhering to the principle of one-time use.

The server considers the authentication request legitimate if the token passes these checks.

Post-verification, the server establishes a session for the user. This session is typically stateless, with a new session token or cookie generated to maintain the user's authenticated state in the application. This session token is separate from the magic link token. It has its own security considerations, such as being HttpOnly and Secure, to prevent access via client-side scripts and ensure transmission over HTTPS only.

Let’s create our own magic links. We’ll use 

 13 with the App Router. We’ll also use 

 for our backend database to store users and tokens.

First, let’s create a new Next.js project:

Once you have created and configured your project, 

 to start it. You’ll see just the default Next.js homepage when you load 

Before we start building out our project, we need to install a few dependencies that we’ll use. Install them using:

: A library that allows for easy email sending.

: A library to implement JSON Web Tokens for secure data transmission.

: The Supabase client library for Javascript.

With those installed, let’s open up the project in an IDE. In total, we’re going to have two pages, two API routes, and two helper libraries:

 will be our homepage. It will have a simple email field, and will call our 

 will be the API route that will create our magic link, send it to the email address passed from 

, and save the token on our Supabase database.

 will be the API route called when the user clicks on the magic link in their email. It will verify the token and redirect the user to the protected dashboard page.

 will be a simple mock “protected page” (that would require the user to be logged in to view it).

 will be a number of database helper functions to save, load, and delete Supabase data.

Let’s start with what the user will see, page.js:

 component, which is responsible for handling the functionality of requesting a magic link via an email address. This component provides a UI for users to request a magic link. Users enter their email and submit the form, triggering a request to the server. Feedback is given to the user through messages and button state changes during the process.

First, we set up the state variables for the page. In the Next.js App Router, you can only use 

 in client-side components. As all components default to server-side, we have to use the 

 directive at the top of the file to show this page has to be rendered on the client. We have three state variables:

: Stores the user's email address. It's updated every time the user types into the email input field.

: Used to display messages to the user, like confirmation or error messages.

: Indicates whether the request is being processed. It's used to disable the submit button and change the button text while the request is in progress.

 function. This is triggered when the form is submitted, and initially prevents the default form submission action with 

 to indicate the start of an asynchronous operation and clears any previous messages stored in 

Then, comes the core part of the component. We make an async 

 endpoint with the user's email in the request body. We then update the 

 state based on the success or failure of the request:

If the request fails, it displays an error message, either from the response or a generic error message.

We have some basic error catching, and then set 

The actual form presented to the user is basic, with just an email input field that updates the 

 state variable on change and a submit button that is disabled and changes its text based on the 

 to send the form details and a paragraph that displays any messages stored in the 

This code handles the API requests related to generating and sending the magic link for user authentication. Let's go through the major components and functions of the code.

 (response) objects as parameters, and then extracts the 

 from the request's JSON body. We then use 

 to search for a user in the database using the provided email. If the user doesn’t exist we send a JSON response indicating the user was not found.

The function then creates the token using 

 to create a JWT with the user's email, signing it with a secret from environment variables and setting an expiration of 1 hour. With that token we can create our magic link. We retrieve the host from the request headers and construct a URL with the generated token as a query parameter.

The generated token is then saved in the database with an associated user ID using 

 transporter with SMTP settings (host, port, security, and authentication credentials) and send an email to the user with the magic link.

Finally, we send back a JSON response indicating that the magic link was sent.

Here, we using one of our helper libraries, 

This is a collection of utility functions designed to interact with Supabase. Each function is designed to interact with specific tables in a Supabase database, which each handle different aspects like token generation, user lookup, token validation, and cleanup. Let's break down each function:

: To save a newly generated token in the database.

 table in Supabase with the user's ID, the token, and an expiration time (set to 1 hour ahead of the current time).

If an error occurs during the database operation, it throws an error with the message received from Supabase.

Returns the data received from Supabase if the operation is successful.

: To fetch a user's data from the database using their email address.

, which is the email address of the user.

 table in Supabase for a record matching the provided email address.

Logs the email and the data received for debugging purposes.

If an error occurs, it throws an error with the message from Supabase.

Need help?

Company

Company

Changelog Nov 5, 2021

Session management as-a-service

<UserProfile/> is now extensible

New Guide: Syncing user data to your backend

Start now,
no strings attached

Pricing built for
businesses of all sizes.

Newsletter!

Company

Company

Changelog Nov 5, 2021

<UserProfile/> is now extensible

Discord and GitLab social sign-in

New Guide: Syncing user data to your backend

Start now,no strings attached

Pricing built for.css-qa8l2m{color:var(--chakra-colors-primary-500);}businesses of all sizes.

Newsletter!

Start now,
no strings attached

Pricing built for
businesses of all sizes.