We've upgraded our `@clerk/nextjs` package to support Next.js 12.2,  Make sure you're on version 3.7.1 or greater.

Peter Perlepes

We're testing out a new email flow.  Our core verification emails are sent through Sendgrid, from 

. Even though we follow all of the best practices, there are a few things we can't account for that still causes some verification/sign-in emails to go to spam.  

For people having trouble, this new email flow should solve your problems:

Emails are sent from `verifications@clerk.dev`

Will only send OTP verifications, since these have historically had less deliverability issues.

If you're having issues, send us an email at `support@clerk.dev` to enable.

Agis Anastasopoulos

Haris Chaniotakis

 - Clerk automatically keeps session tokens alive, now you can customize what data goes into these tokens.  Previously, this was only possible by creating a custom JWT template, and sending it to your backend manually.

Giannis Katsanos

Changelog July 8, 2022

Modern software development typically involves using both software development kits (SDKs) and application programming interfaces (APIs). Even people with experience in the world of application development get tripped up over the fundamental difference between both sets of tools. Both help users improve the functionality of their applications quickly without having to construct something from the ground up. Let’s look at the core differences between SDKs vs. APIs and how they enhance the development experience.

An SDK is often referred to as a dev kit. It’s a set of software-building tools made available from vendors. Developers usually rely on SDKs to build applications using a specific programming language targeted at a particular system or platform. An example of that would be the Windows SDK managed by Microsoft, which contains various frameworks for creating applications that run on Windows computers.

An SDK makes it easier for developers to create applications that follow a standardized pattern for a specific environment. Users download the kit and other components, like prebuilt application examples and instructions. SDKs give you a head-start on building, testing, and deploying a robust application.

An API is a mechanism that helps two software modules communicate using specific protocols and definitions. It's a piece of software designed to fulfill a particular function. The weather app on your phone and the GPS application providing directions are examples of APIs.

The interface part of an API outlines the contract used between two applications attempting to speak to each other. Your API defines the request and response format used between the two. Developers can refer to the documentation for APIs to understand how they can set up requests and responses within applications built using an SDK.

The architecture of your standard API typically consists of client and server functions. An application making a request is the client, while the one providing the response is the server. Your weather app calls the weather service database, asking for information, and the database provides information about the atmosphere in your specific location.

 The Simple Object Access Protocol exchanges messages between clients and servers using an Extensible Markup Language (XML) format. The format became popular among developers in the past. The biggest drawback is the lack of flexibility in structuring requests and responses.

 Remote procedure calls ask the client to execute a function, called a procedure, from a server. That server processes the output and sends it back to the client.

 Representational state transfer APIs define functions used by clients to access data from a server. Both clients and servers use HTTP to exchange information. REST APIs do not preserve data between client/server requests. Responses from servers are sent using plain data.

 Instead of XML, WebSocket APIs rely on JavaScript Object Notation (JSON) to pass data back and forth. It’s a more modern approach that allows for two-way communication between clients and servers. The ability for servers to send callback messages to connected clients increases its efficiency versus REST APIs.

How a Software Development Kit Differs From an Application Programming Interface

The most significant difference between an SDK vs. an API is in how they enable development. Your SDK provides the building blocks you need to write new programs designed for specific platforms using your preferred programming language. There’s often at least one API included with most SDKs. Everything you need to construct a basic app comes with an SDK.

Developers can’t use APIs to build brand-new applications. However, they do allow applications to work together to enhance various aspects of your applications. For example, you can use an API to pull financial data and feed it into a dashboard featured on a website.

Let’s look at features that are often included when you download an SDK.

An integrated development environment (IDE) is used for creating various applications. The platform brings together numerous tools that developers rely on with one graphical user interface (GUI). Here’s a breakdown of the components of a typical IDE:

 Developers use this screen to write software code. A source-code editor often comes with options to highlight specific syntax, point out bugs, and auto-complete phrases in lines of code to help speed up development.

 This utility automates tasks used to set up local software builds for a developer. Build automation performs functions like packaging binary code and running automated tests.

 An IDE toolbar resembles one found in a word processor. It organizes different components that developers rely on as they are writing code.

IDEs help enhance a software engineer’s productivity thanks to the way they standardize the configuration of various developer tools. Everything you need is available through one interface.

A debugger is a computer program that tests and finds bugs within a developer’s code. The debugger typically starts working as soon as you begin writing your code. As you compile your code and integrate it with other programming components, your debugger will highlight errors that keep the program from running correctly. Debuggers are essential to the development process, especially if you’re working on an application containing thousands of lines of code. You can also integrate unit testing to make things easier.

Code samples show developers how to implement different programming scenarios or concepts. They’re also helpful in showing you how to set up more complex architecture components, like a grid. Many SDKs provide you with complete applications and the source files needed to run the program.

One of the main rules that programmers follow is "Don’t Repeat Yourself," or DRY. Code libraries help you stick by that principle by providing prewritten code that you can modify. These reusable blocks of code make it easy to save time while building projects or optimizing other pieces of your program. Another advantage of using tested code libraries is that they add stability to your application.

The documentation that comes with SDKs provides you with instructions on using each component and integrating it with other systems.

APIs that come with SDKs contain libraries built using the platform’s core language. You can use your SDK to leverage APIs that add more capabilities to your program.

The Benefits of an SDK for Software Developers

SDKs make your job as a developer more straightforward by making it easier to pull different components together to construct an application. They make integrating standard processes easier and allow you to access pertinent information while coding. Many SDKs come with built-in support and documentation to help you leverage the program effectively.

Enhanced Control of User Interface and User Experience

An SDK gives you more control over the elements used to build your user interface. If a customer wants components laid out in a certain way, you can follow their requirements seamlessly with an SDK versus trying to use a basic code editor and disparate libraries. You’ll also have an easier time testing each screen element and ensuring that the users will be happy with the final product.

The code samples provided with SDKs allow you to create or expand the functionality of your applications quickly. You can leverage APIs and other libraries to quickly set up new components for your program. That makes the application easier to debug, test, and deploy in different environments before you release it for general use.

Broader Integration Options for Existing Tech Stack

With more vendors choosing to integrate APIs into their SDKs, there are more integration options available for developers. For example, if you have an application built using the .Net framework, you can still integrate the SDK with other frameworks to enhance the look of your UI.

Types of and Common Uses for Development Kits

While some SDKs enable connections between different tools, others help your applications run on specific devices and operating systems.

Many hardware providers make SDKs available to developers for programming technology like the Internet of Things (IoT) or programming robots. Having an SDK readily available for specific hardware makes it easier for developers to start their coding.

While most SDKs come from specific vendors, you can find open-source SDKs that allow developers to modify the underlying source code. However, there can be security risks associated with working with an unsupported platform.

In contrast to open-source SDKs, developers can’t access and modify proprietary source code. Instead, they must purchase a license permitting them to use proprietary code elements.

Below are examples of SDKs available for different programming languages:

Do You Need Both an API and an SDK for Development?

It’s possible to build applications using an SDK without relying on APIs. However, working with APIs and SDKs together helps enhance the programming experience. It’s easier to construct platforms that meet your requirements. There are SDKs available for both Apple and Android developers who want to create mobile apps for those environments.

You don’t have to think of it as a choice between using either an SDK or an API. Remember, many SDKs come with preinstalled APIs. If you want to build a website that allows users to sign in through their Facebook account, an SDK makes that much easier.

You can automate user verification using the Facebook Graph API. That way, you, as the developer, don’t have to go through the trouble of figuring out how to generate tokens, inspect them, and determine which app the user is trying to connect through. The API makes the sign-in process for your app seamless.

SDKs help developers quickly add functionality to their applications and construct standard components. Typically, there’s no need to integrate an SDK with other elements. If you do, that might slow down your development process.

Most software engineers rely on SDKs to complete simple functions like allowing users to make mobile payments or setting up location services. Certain SDKs let you do more complex programming, like creating virtual reality (VR) and augmented reality (AR) programs.

When used correctly, SDKs help relieve the back-end burden of building software programs. You have a modular foundation to rely on that saves you much of the manual effort. Many of the apps created by software engineers contain a few features that serve a common purpose.

For example, a telemedicine app might offer chat features that let users reach out to medical professionals with questions or concerns. A mobile insurance app would contain features that allow users to check on a claim payment's status or print out a copy of their insurance card.

The efficiency provided by an SDK makes it easier for dev team members to work independently. It limits the number of common touchpoints, decreasing the risk of one person breaking another team member’s code during an update.

Adding APIs into the mix cuts down on lag time because of the research needed to figure out how to build a new capability. Working with an API means developers have to worry only about the necessary pieces that make their application work the way they want it to, eliminating the need to dive into how everything works under the surface.

Some SDKs have agreements to which you must provide consent before you are allowed to use the software. Vendors often make new versions of SDKs available for alpha or beta testing, meaning they are not yet publicly available. Those features you try out could undergo modifications or changes before the SDK’s general release. Certain features may fall under a license agreement, so you have to be careful that you do not develop a project that falls outside of its scope.

Read through all the documentation of any SDK you want to use and make sure there is nothing that conflicts with your desired usage. You can’t develop proprietary apps using an SDK with a General Public License. You should also look for any constraints around SDKs that come with a Lesser General Public License (LGPL) if you intend to build a project containing proprietary elements. Think about the ease of implementing security features like multifactor authentication.

Organizations also have to think about the cost of using an SDK. Many are tempted to use open-source SDKs because they’re free. However, your company could still end up paying if there’s a need for developers to spend hours getting up to speed on how the software functions. The cost of the time lost trying to figure out how an open-source SDK works could exceed what you might pay for a licensed version.

Commercial products do bring expenses associated with paying for licenses and integrating the components into current applications. However, you can turn to the vendor for support when you have questions. Paid SDKs tend to be more secure, which lowers the risk of your SDK becoming a gateway for a cyberattack.

You also have to think about the ease of using the SDK in your development shop. The goal of an SDK is to make coding easier. If you’re spending more time getting the application to function correctly than building software, there's a problem. Think carefully about implementing an open-source SDK. If your company has knowledgeable staff who are comfortable working with the product and bringing other developers along, you can succeed.

Usability is often the most significant advantage commercial products have over open-source SDKs. Even if you have developers who are capable of leveraging an open-source SDK, you have to think about who might be asked to maintain those applications if they end up moving on to another position or leaving the organization. How easy will it be to bring other software engineers up to speed on the SDK?

You should also look at the support provided by the SDK manufacturer. With open-source SDKs, there may be only online communities to turn to instead of a fully knowledgeable staff. If you have questions, there’s no guarantee that you’ll get timely answers or that there will be someone available who can help.

SDKs provide developers with everything necessary to create or modify applications. Many come with prebuilt code that helps software engineers get started on their applications. APIs create connections between two applications and allow developers to expand the functionality available within a program.

It’s easier for developers to become more efficient by using SDKs and APIs together. When deciding on an SDK, look at whether you’re really saving by going with an open-source version when it comes to the cost, time, and effort. If your development team is unfamiliar with the platform, you could lose time and money trying to adapt.

Make sure that your SDK does not come with license restrictions that would impact your development. Explore the support that would be available to you or your dev team if you were to run into problems with your SDK.

What Is an SDK and How Is It Different From APIs?

Clerk started with a simple vision. We loved the professionalism of Google's Sign Up, Sign In, and User Profile, so we set out to build developer tools that would help everyone match their caliber.

With UIs as our primary goal, we realized that Clerk wouldn't be a traditional API company. We focused on building a fantastic frontend component SDK, rather than a traditional backend REST SDK.

We chose React as our first target given its popularity, and split Google's surface area into four components: 

Components are a higher-level of abstraction than REST SDKs. They provide UIs to end-users instead of just a function to developers, so they inherently offer more value.

 more value. Even at Clerk, we assumed we could just "slap a UI on top of an auth API." Despite having a team full of seasoned engineers, we failed to realize just how much work sits between traditional APIs and the end-user features they enable.

As an example outside of authentication, let's compare Stripe's original 9 lines for creating a charge, to the 

 for their current Checkout documentation:

Checkout has far more complexity than the original Charge API, but why? Aren't both responsible for charging a customer?

The difference is that Charge asked for the exact amount to charge, while Checkout needs to display 

 an amount is being charged. It needs all of the context of the Products being purchased, their Price, the quantity, the taxes and shipping costs, any discounts applied, and more. Stripe needed to build dozens more API resources and paramaters to produce the end-user Checkout UI.

Before Checkout, this additional context lived inside the developer's application. Now that it lives inside Stripe, charging customers has become massively easier. Stripe solves so much more complexity for developers today than it did 10 years ago.

Clerk is seeing the same patterns in authentication that Stripe saw in Checkout. To build our core components, we need to manage much more complexity than legacy vendors like Auth0.

 components. We are the only authentication provider to offer these, and there's a foundational reason why: 

Clerk is the only authentication provider that manages sessions as-a-service. 

Legacy vendors focus on just the sign-up and sign-in screens. Once the user's identity is verified, the session is managed within the application – not within the authentication service. This makes it impossible for them to offer drop-in 

And since we're not ones to cut corners, our session management solution is fully featured. We include active device management from within 

, so users can remotely force sign outs from other devices:

Plus, we (optionally) include account switching within 

Beyond session management, we also enable self-serve two-factor authentication from within 

 will automatically request the second factor during the next sign-in:

If Clerk didn't manage sessions and two-factor authentication, developers would be stuck implementing these features from within their application – a much more challenging prospect than simply using 

Some readers may be aware that Clerk uses embeddable components while Stripe Checkout uses a redirect flow. That's completely correct, so we kept this blog focused on points that remain true regardless of how the UI is ultimately presented to the end-user.

That being said, there is one advantage to components that deserves a special callout:

At Clerk, every component we build is composed using React hooks, and the hooks we use are actually pacakaged alongside our components. So, if frontend developers don't like our components for any reason, they can still build their own UIs 

without involving a backend developer and a backend SDK.

This extra layer of composability has been a huge boon for companies with strict branding requirements, since we eliminated the need for backend application logic regardless of if our UIs are used.

We've seen this pattern enough to say confidently: 

Components have become the new gold-standard in developer tools – they are the new, optimal, composable building block. They save developers far more time than traditional REST SDKs, both by providing end-user UIs, and by eliminating huge swaths of code that used to be managed in-house.

A ‹Component/› is worth a thousand APIs

Clerk is launching our first Web3 authentication factor - Sign in with Metamask!

This launch is the result of dozens of developer interviews, focused on understanding if and how Clerk can contribute to the Web3 ecosystem.

It didn't take long before we discovered three common challenges that we can help Web3 developers with immediately: securing sessions, multifactor authentication, and profile enrichment.

First and foremost - we found a near ubiquitous challenge around securing sessions. It's a two-part problem: 

How do you verify a user is owns of a Web3 account?

How do you safely create a session to persist the users account information?

 determine the Web3 account address of a user visiting your website with Metamask connected, just run the following Javascript:

Verifying that the returned address is accurate, however, is significantly more challenging. Developers must ask users to sign a transaction, which is a process that undergone several protocol revisions and is hard to keep up with.

This is where Clerk steps in - all the work of signing a transaction and verifying the signature is abstracted away, and wrapped in a `<SignInWithMetamask/>` button.

Let's be honest - persisting a session isn't a Web3 challenge at all, but it is one that Web3 developers must endure by virtue of operating in Web2 browsers.

We know Web3 developers don't want to think about things like httpOnly cookies, XSS attacks, and session revocation. Web2 developers don't either, and that's why built-in 

 is the foundation of every authentication product at Clerk. We use stateless JWTs that enable authentication in under 1 millisecond, and revocation in under 1 minute. We follow all the best practices so you can focus on building your application.

Sign in with Metamask uses the same abstraction as our other authentication factors like passwords or magic links.

 works with Metamask users out-of-the-box.  Users simply need to navigate to their user profile and opt-in to multifactor authentication. There's no extra work for the developer beyond mounting a 

 component, or redirecting to the Clerk-hosted component.

Off-chain profile enrichment is a topic of much debate in the Web3 community. Ideally, data like email addresses and phone numbers could be retrieved on-chain following the principles of 

But as of today, there are no standard protocols for retrieving this data. As a result, top Web3 companies like OpenSea still collect and verify email addresses off-chain.

Clerk enables developers to easily do the same. We provide simple helpers for collecting and verifying phone numbers, email addresses, and even OAuth accounts. Beyond that, we accept structured data likes names and profile photos, as well as provide a generic metadata field for bespoke profile enrichment.

In the future, we look forward to enriching profiles in a more decentralized manner. Today, we hope this mechanism can help bridge the gap from Web2 to Web3.

Try out our guide for installing Web3 authentication.

  The guide will get you started with a new Next.js application with Metamask authentication.

This launch is the first of many upcoming Web3 launches. Our rough roadmap ahead includes:

 - we know that Metamask alone is a little limiting and will add generic Ethereum support soon

- In the Web2 realm, our team is actively building authorization via Roles and Permissions. We see many corollaries to Web3 authorization via token gating are approaching the primitives in a way that will support both.

 - Because we fully anticipate a multi-chain future

Need something we didn't mention? Please reach out through any of our 

 - we're still defining this roadmap and very interested to hear how we can better meet your needs.

Introducing Web3 Authentication

In this article, we are going to explore how we can use 

 to build a very basic todo app. Thanks to Clerk’s simple and powerful authentication options we're also going to add a complete User Profile, and even Multi-factor authentication (MFA).  

Why would you add MFA to a simple todo app? Because even todos deserve to be protected with the best security. And... Clerk makes it insanely easy to do so!

Configuring Clerk for authentication by setting up Social SSO, password-based authentication, email magic links, and multi-factor authentication via SMS passcodes.

Configuring Supabase as a backend for a Postgres database, row-level security (RLS) and authorization policies

The source code for the final version can be found 

 is a lightweight react framework that’s optimized for developer experience, and gives you all the features you need to build powerful interactive applications.

 is a powerful authentication solution specifically built for the Modern Web. Clerk lets you choose how you want your users to sign in, and makes it really easy to get started with a suite of pre-built components including <SignIn />, SignUp />, <UserButton />, and <UserProfile />. Clerk also provides complete control with intuitive SDKs and APIs.

 is an open source Firebase alternative. It lets you easily create a backend with a Postgres database, storage, APIs and more. It also has an authentication module, however, for this tutorial we will only be using the database.

The quickest way to get started with Next.js is with the official create-next-app template.

In your terminal, create your app with the following command:

Let’s start with a simpler base by removing most of the Next.js template, and adding a basic nav bar, with a content area for our home page.

Since this is not a CSS tutorial, we'll use some very basic styling and add it all up front.  

As promised, our basic home page will include a simple nav bar and body.

It's going to be beautiful... Let's run our app, and see where we're starting!  

In your terminal, start your application with the following command:

It's easiest to start an app like this with our user object in place, and with a complete authentication foundation.  Then, we can build everything else on top.  Clerk gives us very simple and complete building blocks that makes this whole process very easy.

 to Clerk. Once you verify your email address, you'll be greeted with a way to create your first application:

I'm choosing the default settings, which will collect an email and password, or have users sign in with google.  You can choose whatever you'd like, and once your application is created, you can fine-tune them a lot more in the Clerk dashboard.

When you create a new application, a new development instance is automatically created for you, which is optimized for local development.

Instances in Clerk take a few minutes to be completely ready. Behind the scenes resources are being spun up, DNS records are being set, and certificates are being created.  These take time to fully propagate across the internet, so if you see any errors, give it a minute and refresh.

Now you're going to add sign up and sign in forms, and build a "protected" page, that only signed in users can see.

 to your project. Clerk brings a ton of authentication capabilities to 

, but for this tutorial we'll just set up the basics of sign-up and sign-in.  In your terminal, at the root directory of your project, install the 

this tutorial will be using the latest alpha release, so make sure you're on at least version >=3.0

Now you need an environment variables to link your local development with your Clerk instance.

You can find your API keys on the home page, in the "Connect your application" section.

In your project’s root directory, create a file named 

 . Next.js will automatically load all environment variables set here, into your application.  Because we're not using a custom backend at all, you only need your Frontend API key

Get the values from the dashboard, add the following to your 

 Keys prepended with NEXT_PUBLIC are exposed to your javascript, so do not put 

Any time you add or change your environment variables, you'll need to restart your application, so go to your terminal and kill the running application with 

 and relaunch it with the following command:

Great! although nothing changed, your application can now properly see these environment variables.

Now you can use Clerk's helper components to build a "gated" page.  In order to use these helpers, you should expose the Clerk context to your entire application, by wrapping the top level component with a 

 is the top level of your application. By wrapping the 

 here, every part of your application will have access to the Clerk context.

, add a sign in button and some basic gated content.  We'll use the following Clerk-provided hooks and components:

 - hook to easily access the current user, and it's state

 - displays a "UserButton" for the current user

The header now shows either sign in/up buttons or a 

, depending on your state.  The content section of this page follows similar logic.  Go ahead and sign up, if you sign up with Google, it will pull your profile image, and you will be able to see your 

Clerk provides a lot of hooks, components, and helpers -- you can explore all of them 

There's even more to explore with this application.  The 

You can do a lot from this page, including:

See what devices your logged into, (and log out of unrecognized devices) 

That's right, you don't need to write any more code to add MFA to your application.  Clerk handles it out of the box.  Just go to the 

 tab in your user profile, and follow the steps to add your phone number as a second factor!

This sample app is leveraging Clerk-hosted UIs, which is the simplest implementation path.  There are other ways you can add build this features, including 

 on a page you control, or by building it with a completely custom UI, using the 

Now that your user management foundation is in place it's time to connect to a database and create some todos!

This tutorial is using Supabase as a backend.  Supabase is a very powerful, open-source, postgres-based, database platform.  It will be great for easily storing your todos, and even work as your API.

The first thing you'll need is a Supabase account, which can be created 

. Once you have an account, create a new project.  

And choose the region closest to you, or your users.

Supabase takes a little while to spin up, but once it’s ready, go to the Table editor and press the "Create a new table" button

 and, add 2 new columns to the table named:

For each of the new columns, press the cog and deselect 

With Row Level Security enabled, postgres (and thus Supabase) will deny access to every row by default. So, you will need to setup up some "Policies" that will allow the 

 to access their own rows, and that will let them create new rows for themselves.

Before creating your "RLS Policies", Supabase will need a way to figure out which user is making the current request. You normally would be able to use Supabase's built-in 

currently an issue that we're working to resolve

! Upvote it so the issue can get more attention :) 

The workaround is easy enough though - you will create your own 

function named that accomplishes the same thing as 

NextJS + Supabase + Clerk: Build a simple todo app with multifactor authentication

In short: HttpOnly cookies do not prevent 

 attacks, but they do lessen the impact and prevent the need to sign out users after the XSS is patched. HttpOnly cookies are not a substitute for XSS prevention measures.

Our very first architecture decision at Clerk was to use HttpOnly cookies for session management. It has long been understood that HttpOnly cookies help mitigate cross-site scripting (XSS) attacks, and we felt it was important to include this best-practice directly in our product.

But while there's strong consensus that using HttpOnly cookies is a best practice, we've found many developers are unsure of how they help with XSS. We think this stems from the guidance, which often just says what to do rather than explaining why:

A cookie with the HttpOnly attribute is inaccessible to the JavaScript

 API; it is sent only to the server. For example, cookies that persist server-side sessions don't need to be available to JavaScript, and should have the HttpOnly attribute. This precaution helps mitigate cross-site scripting (

Cookies [...] SHOULD be tagged to be inaccessible via JavaScript (HttpOnly).


Changelog July 8, 2022

Next.js 12.2

Emails w/ High Deliverability

Backend API updates

Ready to see what Clerk can do?

Pricing

Changelog July 8, 2022

Next.js 12.2

Emails w/ High Deliverability

Sign in with Line

Backend API updates

Ready to see what Clerk can do?

Pricing