# Clerk Blog — Page 6
# Comparing Clerk Webhooks vs Backend API
URL: https://clerk.com/blog/webhooks-v-bapi.md
Date: 2024-08-29
Category: Guides
Description: Learn when to use Clerk Webhooks or the Backend API to efficiently access user data and avoid unnecessary complexity.
This post compares Clerk Webhooks and the Backend API, focusing on their roles in querying user data specifically.
Whether you need to query information about a specific unauthenticated user, a list of users, or synchronize Clerk user data with another system, this comparison will help you choose the best option for your circumstances.
> \[!IMPORTANT]
> This guide specifically addresses situations where querying data about unauthenticated users is necessary. For guidance on reading data about the currently authenticated user from your server or client, please refer to [A guide to reading authenticated user data from Clerk](/blog/read-user-data-guide).
## What is the Backend API?
The [Clerk Backend API](/docs/reference/backend-api) is designed to query or update information from your Clerk application, such as user data.
You can query users one at a time, or, if you need a list of users, it's possible to effectively batch the query to improve efficiency.
Backend API requests are [limited](/docs/backend-requests/resources/rate-limits) to 100 per 10 seconds for your Clerk application. While the Backend API is straightforward to use, you should be judicious so as not to exceed your request allowance, otherwise, your application might stop working properly.
### How does the Backend API work?
The easiest way to interface with the Backend API is by using a Clerk backend SDK. The most popular option is the [JavaScript Backend SDK](https://clerk.com/docs/references/backend/overview) although there are [others](https://clerk.com/docs/references/overview).
To retrieve a specific user, call [`getUser`](/docs/references/backend/user/get-user) with their identifier. This awaitable function returns a [Clerk `User` object](/docs/references/backend/overview) populated with all the information Clerk stores about the user.
```ts {{ title: 'getUser Example' }}
const userId = 'user_123'
const response = await clerkClient.users.getUser(userId)
console.log(response)
// _User {
// id: 'user_123',
// passwordEnabled: true,
// totpEnabled: false,
// backupCodeEnabled: false,
// twoFactorEnabled: false,
// banned: false,
// locked: false,
// createdAt: 1708103362688,
// updatedAt: 1708103362701,
// imageUrl: 'https://img.clerk.com/eyJ...',
// hasImage: false,
// primaryEmailAddressId: 'idn_123',
// primaryPhoneNumberId: null,
// primaryWeb3WalletId: null,
// lastSignInAt: null,
// externalId: null,
// username: null,
// firstName: 'Test',
// lastName: 'User',
// publicMetadata: {},
// privateMetadata: {},
// unsafeMetadata: {},
// emailAddresses: [
// _EmailAddress {
// id: 'idn_123',
// emailAddress: 'testclerk123@gmail.com',
// verification: [_Verification],
// linkedTo: []
// }
// ],
// phoneNumbers: [],
// web3Wallets: [],
// externalAccounts: [],
// lastActiveAt: null,
// createOrganizationEnabled: true
// }
```
When you need to fetch a list of users by their IDs, [`getUserList`](/docs/references/backend/user/get-user-list) effectively batches `getUser` queries into one. This is not only simpler than sending and handling a sequence of requests, it's more efficient as well. Because this operation initiates only one API call under the hood, your backend request allowance goes further.
```ts {{ title: 'getUserList Example' }}
const userId = ['user_123', 'user_456']
const response = await clerkClient.users.getUserList({ userId })
console.log(response)
// {
// data: [
// _User {
// id: 'user_123',
// passwordEnabled: false,
// totpEnabled: false,
// backupCodeEnabled: false,
// twoFactorEnabled: false,
// banned: false,
// locked: false,
// createdAt: 1707561967007,
// updatedAt: 1707561967095,
// imageUrl: 'https://img.clerk.com/eyJ...',
// hasImage: true,
// primaryEmailAddressId: 'idn_123',
// primaryPhoneNumberId: null,
// primaryWeb3WalletId: null,
// lastSignInAt: 1707561967014,
// externalId: null,
// username: null,
// firstName: 'First',
// lastName: 'Test',
// publicMetadata: {},
// privateMetadata: {},
// unsafeMetadata: {},
// emailAddresses: [Array],
// phoneNumbers: [],
// web3Wallets: [],
// externalAccounts: [Array],
// lastActiveAt: 1707523200000,
// createOrganizationEnabled: true
// },
// _User {
// id: 'user_456',
// passwordEnabled: false,
// totpEnabled: false,
// backupCodeEnabled: false,
// twoFactorEnabled: false,
// banned: false,
// locked: false,
// createdAt: 1707539597250,
// updatedAt: 1707539597331,
// imageUrl: 'https://img.clerk.com/eyJ...',
// hasImage: true,
// primaryEmailAddressId: 'idn_456',
// primaryPhoneNumberId: null,
// primaryWeb3WalletId: null,
// lastSignInAt: 1707539597260,
// externalId: null,
// username: null,
// firstName: 'Second',
// lastName: 'Test',
// publicMetadata: {},
// privateMetadata: {},
// unsafeMetadata: {},
// emailAddresses: [Array],
// phoneNumbers: [],
// web3Wallets: [],
// externalAccounts: [Array],
// lastActiveAt: 1707523200000,
// createOrganizationEnabled: true
// }
// ],
// totalCount: 2
// }
```
While the focus of this post is querying user data, the Backend API also supports manipulating user data with `createUser`, `updateUser`, and specific helpers like `banUser`. Additionally, the Backend API supports similar operations for organizations, sessions, and more.
> \[!NOTE]
> Explore [everything the Backend API has to offer](/docs/reference/backend-api) in the reference documentation.
## What are Clerk Webhooks?
A [Webhook](/docs/integrations/webhooks/overview) is a way for Clerk to send data to another system when specific events happen, such as when a user is created or updated.
They're most commonly used to register events with external systems, send analytics events, and synchronize databases with Clerk.
Think of Webhooks like a notification that automatically sends information to a URL you specify, allowing different systems to react to Clerk to events when they happen.
Webhooks are more complex than calling the Backend API. You need to [verify that the request came from Clerk](/docs/integrations/webhooks/overview#protect-your-webhooks-from-abuse), manage occasional duplicate and out-of-order events, plus handle the asynchronous nature of Webhooks, which can complicate building synchronous workflows such as a [custom onboarding flow](/blog/add-onboarding-flow-for-your-application-with-clerk). Despite these challenges, Webhooks do not enforce any rate limits. Clerk will send as many Webhooks events as your server can handle.
### How do Clerk Webhooks work?
To enable Webhook events, register your Webhook endpoints from the dashboard. Once configured, Clerk will push event data to these endpoints as events occur in your Clerk application.
Example events:
- `user.created`
- `user.updated`
- `user.deleted`
> \[!TIP]
> Configure your Webhook endpoints to receive only the necessary event types for your integration. Listening for unnecessary or all events can strain your server, which we strongly advise against.
Clerk uses svix to ensure Webhooks are delivered reliably with [retries and other mechanisms](/docs/integrations/webhooks/overview#how-clerk-handles-delivery-issues).
> \[!TIP]
> [Learn more about Webhooks](/docs/integrations/webhooks/overview) and [how to debug them](/docs/integrations/webhooks/debug-your-webhooks) in the documentation.
## Comparing Webhooks vs Backend API
Below is a table summarizing the differences between Webhooks and the Backend API.
Use it to understand your options at a glance or reference the next time you return to this page.
| | Backend API | Webhooks |
| ------------------------- | --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| Purpose | Directly query and manipulate user data from Clerk. | Used to send events from Clerk to another system, allowing for automated and instantaneous communication between systems. |
| Model | Request/response (manual fetching or polling). | Event-driven. |
| Response handling | Initiate and `await` API responses. | Must handle events asynchronously. |
| Implementation complexity | Requires API calls, typically simpler to implement. | Requires setting up reliable and secure endpoints to receive Webhooks. |
| Scalability | Dependent on rate limit. | Can handle high volumes of events when needed. |
| Reliability | Highly available. | Dependent on the quality of your Webhook endpoint implementation. |
| Example | Example functions: `getUser` and `getUserList`. | Example events: `user.created`, `user.updated`, and `user.deleted`. |
Key differences:
- **Complexity** Using Webhooks to keep your database in sync with Clerk can be more complex than calling the Backend API due to their asynchronous nature.
- **Rate limits** The Backend API imposes rate limits, which can impede your application's functionality if exceeded. You can often avoid these limits by using [alternative methods to read authenticated user data](/blog/read-user-data-guide) and by batching queries with `getUserList` when appropriate. Unlike the Backend API, Webhooks don't have rate limits. For this reason, synchronizing your database with Clerk using Webhooks is a viable alternative to the Backend API if you are likely to surpass the request allowance.
- **Always up-to-date** When you query records from the Backend API, you query the freshest data from the source of truth. This is in contrast to reading from a database synchronized with Clerk using Webhooks, which might not have received the latest events yet.
- **Synchronous vs asynchronous** With the Backend API, you control when to initiate an API call and how to handle the response, making it a predictable method. By comparison, Webhooks provide an asynchronous mechanism to receive and react to events. They are best used for things like sending notifications or updating systems where it isn't critical that the data is immediately up-to-date. For example, an email provider for weekly newsletters or an analytics platform for daily event rollups.
- **Adding or updating resources** The Backend API is suitable for both querying and manipulating data, unlike Webhooks which can only react to events.
## Guidance
### When the Backend API is better
- **Straightforward access** The Backend API is the most straightforward tool to programmatically query the most up-to-date data from Clerk. It can support a variety of use cases, provided you don't encroach on the rate limits.
- **Synchronous events** The Backend API's request-response pattern is well-suited to operations that require synchronization or that must act in a serialized fashion, such as an onboarding flow.
### When Webhooks are better
- **Integrations** Webhooks are the preferred method to update external systems with data from Clerk. Use them to notify another system like an email platform or CMS when a new Clerk user is created or if they update their email.
Or send events to an analytics platform like Google Analytics or [Posthog](/blog/how-to-use-clerk-with-posthog-identify-in-nextjs).
You can even use Webhooks to [create new user notifications in Discord or Slack](https://x.com/r_marked/status/1816551015543447575)!
- **Synchronizing Clerk with your database** The Backend API limits can be restrictive for certain applications. For instance, a B2C social media application where you frequently need to render user information with their posts. In such cases, you would likely hit the Backend API limit quickly. Webhooks provide a means to synchronize your database with Clerk. You can then query your database to the sidestep rate limit.
---
# Automate Neon schema changes with Drizzle and GitHub Actions
URL: https://clerk.com/blog/automate-neon-schema-changes-with-drizzle-and-github-actions.md
Date: 2024-08-22
Category: Guides
Description: Learn about schema migrations and how they can be applied to a Neon database with Drizzle and GitHub Actions
While it’s relatively straightforward to deploy updated code to different environments, applying the same techniques to a relational database can be disastrous.
Application code is stateless, meaning you can rebuild the code to recreate the application at any time. In fact, when deploying updated code to platforms like Vercel, the tooling will simply build and ship the latest version of the application, overwriting the previous one.
However, databases are stateful since the value is in the data contained within them. Applying the same deployment methodology to a database (removing and replacing it with a new version) would be detrimental to your users or business.
In this article, you’ll learn what schema migrations are, how they can be used to safely make database changes, and how to automate those changes to a Neon database using Drizzle and GitHub Actions.
## What is a schema migration?
Schema migrations are a way to apply changes to the schema of a database in a controlled way.
Typically each schema migration is a SQL script that is applied to the database to update the schema to the latest version. The migration files can stored in version control so the state of the schema can be tracked over time.
Schema migrations are used for updating the database schema as changes are required, but can also be used to create new environments. To recreate the database up to a specific point in time, the migrations can applied in the same order they were generated.
### Schema migrations and deployments
When building an application that uses a relational database, you’ll often have a different database per environment. Each database is isolated from one another so modifying the schema in one database environment does not affect the others.
Let's say you have two environments, a dev environment for building new features, and a production environment that your users are actively using.
When a feature is complete, merging your code from the `dev` branch to `main` is relatively straightforward. Once the newest version of the application is built, the artifacts of that build are deployed into the production environment, replacing the previous version.
The latest schema migrations are also applied to the database, updating the schema to support the latest version of the application. If done properly, all of the data within the database will remain intact.
## How to generate and apply schema migrations with Drizzle
Now that you understand what schema migrations are and how they are used when deploying new versions of your database, let’s explore a practical example using Drizzle.
Drizzle is a type-safe ORM for applications built with TypeScript. The team also built Drizzle Kit for managing the schema of the database. Drizzle Kit can be used to analyze your TypeScript models, generate schema migrations from the models, and apply them to the database.
### The demo application
The remainder of this article uses a sample to-do app to demonstrate how to use schema migrations to apply database changes. The application uses a Postgres database hosted by Neon, with a relatively simple schema.
I’ll be showing the process of adding a single column to the `tasks` table (shown below) so that each task can have a description stored with it.
To simulate multiple environments, the Neon database has a `main` branch that contains the production data and a `dev` branch that is an isolated environment used for adding and testing new features.
> \[!NOTE]
> All of the code shown in this article is available [on GitHub](https://github.com/bmorrisondev/team-todo-demo).
### Updating the development environment
I’ll start by updating the code on the `dev` branch to support a “description” field of the `tasks` model:
```ts {{ filename: 'src/db/schema.ts', ins: [8] }}
export const tasks = pgTable('tasks', {
id: serial('id').primaryKey(),
name: text('name'),
is_done: boolean('is_done'),
owner_id: text('owner_id'),
created_in: timestamp('created_on'),
created_by_id: text('created_by_id'),
description: text('description'),
})
```
The application has the following `drizzle.config.ts` which Drizzle Kit uses to locate the schema files in the project, generate and store migrations, and connect to the database:
```ts {{ filename: 'drizzle.config.ts' }}
import type { Config } from 'drizzle-kit'
export default {
schema: './src/db/schema.ts',
out: './drizzle',
dialect: 'postgresql',
dbCredentials: {
url: process.env.DATABASE_URL as string,
},
verbose: true,
strict: true,
} satisfies Config
```
Next, I’ll run the following command which will generate a new schema migration file. I’m also setting the `DATABASE_URL` environment variable used by `drizzle.config.ts`:
```bash
export DATABASE_URL=postgresql://teamtodo_owner:mydbpass@ep-weathered-wildflower-a5okjpjr.us-east-2.aws.neon.tech/teamtodo?sslmode=require
drizzle-kit generate
```
A new file is automatically generated and placed in the `drizzle` folder with the necessary SQL to apply:
```sql {{ filename: 'drizzle/0001_loose_mojo.sql' }}
ALTER TABLE "tasks" ADD COLUMN "description" text;
```
Next, I’ll run the following command to update the database schema in Neon, adding the `description` column:
```bash
export DATABASE_URL=postgresql://teamtodo_owner:mydbpass@ep-weathered-wildflower-a5okjpjr.us-east-2.aws.neon.tech/teamtodo?sslmode=require
drizzle-kit migrate
```
Once the migration is applied, the new column is added to the database and is ready to test. The schema will now look like this:
### Updating the production environment
When I’m ready to move the code to production, I can apply the migrations to the `main` database branch by passing in that branch's connection string:
```bash
export DATABASE_URL=postgresql://teamtodo_owner:mydbpass@ep-frosty-tree-a54nb30r.us-east-2.aws.neon.tech/teamtodo?sslmode=require
drizzle-kit migrate
```
Once the migrations are applied to the `main` database branch, I can deploy the production version of my application. Platforms like Vercel (which I am using to host this application) will commonly monitor the `main` branch of a repository for changes and kick off the deploy process when a change is detected. Merging my code changes into `main` will trigger Vercel’s CI tools to deploy the newest version of the code.
I can deploy my application to Vercel by merging the changes into the `main` code branch and letting Vercel’s CI tools deploy the newest version of the code.
While this example makes a single change, multiple schema migrations can be generated and applied between deployments for more complex schema changes. The files will be applied in the order they were created, ensuring that the state of the production database matches the development environment.
### Automating migrations with GitHub Actions
Using Drizzle Kit to apply schema migrations helps to ensure that your schema is safely updated between deployments, but manually performing this operation introduces a point of failure in the process. If you forget to apply the migrations, and your schema doesn't match what the application expects, you could inadvertently take your service down.
GitHub Actions, a platform built into GitHub, provides a way for developers to define workflows that execute automatically when specific events (such as making changes to a repository branch) occur on GitHub. Let’s look at how GitHub Actions can automatically apply migrations when the code on the `main` branch changes.
First, I’ll need to securely store the connection string for my database in GitHub in a way that the GitHub Actions service can access it. This is done by adding a repository secret in **"Settings"** under **"Secrets and variables"**, then **"Actions"**.
The following GitHub Actions workflow can be used to execute `drizzle-kit migrate` each time a change is performed on the `main` branch in GitHub:
```yaml
name: Apply schema migrations
# 👉 Only run this workflow when a change is made to the main branch
on:
push:
branches:
- main
jobs:
apply_migrations:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v3
- name: Install dependencies & tooling
run: |
npm install
npm install -g drizzle-orm drizzle-kit pg
- name: Apply migrations
run: drizzle-kit migrate
env:
DATABASE_URL: ${{ secrets.DATABASE_URL }}
```
Since Vercel triggers a deployment when changes are made on the `main` repository branch, the Actions workflow will trigger simultaneously with the deployment, ensuring that your code and schema versions always stay in sync.
## Conclusion
Properly applying changes to a database when new features are added to an application is important to retaining the data within the database, as well as maintaining the uptime of your application.
After reading this article, you now understand what schema migrations are and how they’re used in the development lifecycle of a database. You should also know how to use Drizzle to generate and apply migrations, and how to automate this process using GitHub Actions.
---
# A guide to reading authenticated user data from Clerk
URL: https://clerk.com/blog/read-user-data-guide.md
Date: 2024-08-15
Category: Guides
Description: Learn how to access data about the currently authenticated user with Clerk's APIs and session claims.
Reading data about the authenticated user is a fundamental part of any application.
Whether you need to access the user's ID, username, contact information, or profile data, Clerk provides various methods to accomplish this depending on your runtime environment and application needs.
Options are great! But they can also make it challenging to decide which approach to take. I wrote this guide to explain the different methods and their appropriate use cases. This way, you can choose the most suitable and efficient option for your circumstances.
> \[!IMPORTANT]
> This post is about accessing data about the currently-authenticated user. If you want to query data about unauthenticated users, you can use the Backend API or Webhooks. For guidance on which is best for your circumstances, please refer to [Clerk Webhooks vs BackendAPI](/blog/webhooks-v-bapi).
## Methods to read authenticated user data
Below is a table summarizing the different approaches to read authenticated user data from Clerk.
Use it to understand your options at a glance or reference the next time you return to this page.
## Frontend API with `useUser()`
Clerk's [Frontend API](/docs/reference/frontend-api) enables authenticated users to access their own data and perform actions specific to their account from a browser or native environment.
To access the authenticated user, you could call the `/v1/me` endpoint. However, the convenient option in Next.js is to invoke [`useUser()`](/docs/references/react/use-user), which queries `/v1/me` under the hood.
```tsx {{ title: 'useUser()' }}
'use client'
import { useUser } from '@clerk/nextjs'
export default function Example() {
const { isLoaded, isSignedIn, user } = useUser()
if (!isLoaded || !isSignedIn) {
return null
}
return
Hello, {user.firstName} welcome to Clerk
}
```
Certain Frontend API requests are rate-limited but `/v1/me` is not. This endpoint has no defined limit, making it practically unlimited.
### Guidance
When to use Frontend API with `useUser()`:
- Call `useUser()` from a client component when you need to update the UI with information about the authenticated user.
- Best-suited for when you need to dynamically update the UI in response to a client event. `useUser()` returns a [`User`](/docs/references/javascript/user/user) with a `reload()` function that makes it even easier to render the most up-to-date user information.
- Also useful for loading user information on page load, though server-side rendering (SSR) may be preferred for this.
When to avoid:
- `useUser()` won't work from a server environment and is therefore inappropriate for server-side-rendering user information.
- Unsuitable for accessing user private metadata.
- Avoid querying and sending user data from the frontend to the backend. Fetch and verify the data directly on the backend to ensure its integrity.
## Backend API with `currentUser()`
Clerk's [Backend API](/docs/reference/backend-api) is designed to query user data from a server environment.
The [`currentUser()`](/docs/references/nextjs/current-user) helper is used to access information about the currently authenticated user from server components, server actions, and other server-side code like so:
```tsx {{ title: 'currentUser()' }}
import { auth, currentUser } from '@clerk/nextjs/server'
export default async function Page() {
// Get the Backend API User object when you need access to the user's information
const user = await currentUser()
// Use `user` to render user details or create UI elements
}
```
> \[!IMPORTANT]
> `currentUser()` calls Clerk's Backend API behind the scenes. This counts towards your application's [Backend API request rate limit](/docs/backend-requests/resources/rate-limits#backend-api-requests) of 100 requests per 10 seconds.
### Guidance
When to use `currentUser()`:
- Call `currentUser()` from a Next.js server component, server action, API route handler, or other backend code where you require data about the authenticated user.
- Suitable for accessing [user private metadata](/docs/users/metadata#private-metadata).
- A good option when you need to query potentially large attributes such as `user.organizatons` from a backend environment. Dynamic attributes like these are usually too big for custom session claims (session claims are the subject of the next section).
- Suitable for accessing user data infrequently due to rate limits.
When to avoid:
- Do not exceed 100 requests per 10 seconds. This limit applies to *all* Backend API requests made by your application. Exceeding this limit will result in a `429 Too Many Requests` error and your application might not work properly.
- Avoid querying and storing user data in your database. If a user updates their information via a Clerk component like [``](https://clerk.com/docs/components/user/user-profile), your database won't be synchronized. Instead, store only the user ID and fetch the latest user data from Clerk as needed.
> \[!NOTE]
> If you *only* need the authenticated user ID, calling the Backend API is not efficient.
>
> Read the `userId` default session claim with `auth()` or `useAuth()` using the guidance in the [next section](#session-claims) instead.
## Session claims
Claims are pieces of information about the authenticated user. They're encoded in the [Clerk session token](/docs/backend-requests/resources/session-tokens) and digitally signed to ensure the information is authentic.
Claims are accessible from frontend or backend environments, and since they don't require an API roundtrip, rate limits do not apply.
The user ID is included in the token by [default](/docs/backend-requests/resources/session-tokens#default-session-claims). However, the user's username, contact information, and other attributes are not. To access this optional data, it's necessary to customize the session token with custom claims.
### Read user ID
Below are two code examples demonstrating how to access the authenticated user's ID on the client and on the server with the [`useAuth()`](/docs/references/react/use-auth) and [`auth()`](/docs/references/nextjs/auth) helpers respectively:
```tsx {{ title: 'useAuth()' }}
'use client'
import { useAuth } from '@clerk/nextjs'
export default function Page() {
const { isLoaded, userId, sessionId } = useAuth()
// In case the user signs out while on the page.
if (!isLoaded || !userId) {
return null
}
return (
Hello, {userId} your current active session is {sessionId}
)
}
```
```tsx {{ title: 'auth()' }}
import { auth } from '@clerk/nextjs/server'
export default async function Page() {
// Get the userId from auth() -- if null, the user is not signed in
const { userId } = auth()
if (userId) {
// Use `userId` to store an entity in the database
}
}
```
### Set and read custom session claims
To customize session claims for your application, open the Clerk dashboard then click **Sessions**.
Look for the "Customize session token section" and press **Edit**.
Define a JSON structure that includes dynamic placeholders called shortcodes (remember to **Save** after). Clerk will replace these shortcodes with the actual values at runtime:
```json {{ title: 'Claims' }}
{
"firstName": "{{user.first_name}}",
"lastName": "{{user.last_name}}",
"email": "{{user.primary_email_address}}",
"avatarUrl": "{{user.image_url}}",
"publicMetadata": "{{user.public_metadata}}"
}
```
Read custom session claims from a backend environment with the same [`auth()`](/docs/references/nextjs/auth) helper and the returned `sessionClaims` property.
```tsx {{ title: 'auth()' }}
import { auth } from '@clerk/nextjs/server'
export default async function Page() {
// Get the userId from auth() -- if null, the user is not signed in
const { userId, sessionClaims } = auth()
if (userId && sessionClaims) {
const { firstName, lastName, email, avatarUrl, publicMetadata } = sessionClaims
}
}
```
> \[!TIP]
> To get auto-complete and prevent TypeScript errors when working with custom session claims, [define a global type](/docs/backend-requests/making/custom-session-token#add-global-type-script-type-for-custom-session-claims).
Custom session claims are technically accessible from frontend environments, but this is rarely needed, so the Next.js SDK doesn't provide a dedicated helper.
### Guidance
When to use session claims:
- Custom session claims are best suited for scenarios where you need to frequently access certain user attributes from the backend, but the Backend API rate limits would normally be prohibitive.
- In either frontend or server environments, session claims are the most efficient way to access just the user ID. This eliminates the need for unnecessary API calls.
When to avoid:
- The *entire* session token must not exceed 4KB due to browser cookie size limits. Use good judgment when including custom claims such as `user.organizations`, which can cause the token to exceed this limit and break your app. Only store essential, predictably-sized user data in the token, and occasionally fetch larger claims through separate Backend API calls.
- Unsuitable for accessing user private metadata.
- Do not use custom session claims in a frontend environment. It requires less configuration and code to use the Frontend API with `useUser()`, as described at [the top](#frontend-api-with-use-user) of this guide.
---
# Role based access control with Clerk Organizations
URL: https://clerk.com/blog/role-based-access-control-with-clerk-orgs.md
Date: 2024-08-09
Category: Guides
Description: Learn what role based access control is and how to use it with Clerk Organizations to simplify permissions management.
Managing permissions in large SaaS applications can be a nightmare.
Providing team owners a way to grant functionality to users in a simplified way can be the difference between companies purchasing your software or going with a competitor. Clerk provides you with a way to build this functionality with minimal effort. By utilizing roles and permissions built into [Organizations](/docs/organizations/overview), you can implement role-based access control for your users.
> RBAC is essential for B2B applications. [Learn more about our B2B SaaS solution](/b2b-saas) for comprehensive enterprise features.
In this article, you'll learn how roles and permissions in Clerk can be used to allow functionality within an application for a user based solely on the role they are assigned.
## What is Role-Based Access Control?
Role-Based Access Control (RBAC) is a method of managing application security by granting permissions to systems based on the role assigned to the user.
When a user signs into an application, they provide their credentials to prove their identity. This process of the user proving *who they are* is known as Authentication in cybersecurity. Role-based access control is involved in the process of Authorization, which is identifying *what they can do*.
With RBAC, individual permissions can be linked to one or more roles. Roles are often correlated to the job function of the user, granting them access to everything they need to fulfill their duties while preventing them from having access to what they don't need.
As your system evolves, you can simply update the permissions assigned to a given role to grant those members access to new functionality. This approach to security makes security management easier compared to assigning permissions to individual users.
## Implement RBAC with organizations
The example used in this article is built on the concept of a team-based task management app built with Next.js, where each team is an organization in Clerk.
There will be three roles each with a different set of permissions included. Based on the role assigned to the user, their ability to perform operations within the app will vary. The following diagram demonstrates how three separate users with different roles will inherit their permissions:
- Charlie will have the Viewer role and can view the tasks, but not create or modify them.
- Bob has the Member and will be able to add and edit their own tasks, but not tasks created by another user.
- Alice will have the Manager role and will be able to manage all tasks in the organization.
The code referenced in this article is open-source and can be [accessed on GitHub](https://github.com/bmorrisondev/team-todo-demo/tree/article-3) in the `article-3` branch.
## Defining custom roles and permissions
When you enable organizations for a Clerk application, there are two default roles and a set of default permissions.
The Admin role contains all of the necessary permissions to manage the organization and its members, and the Member role can view the active organization, but not manage it. Developers can create custom roles and permissions that can be assigned by organization administrators as well, located in the Clerk dashboard in the **"Organization settings"** of the side nav under **"Roles"** and **"Permissions"** respectively.
In this example, there are three custom permissions created:
| Name | Key | Description |
| ------------ | ------------ | --------------------------------- |
| Manage tasks | tasks:manage | Allow users to edit all tasks. |
| Edit tasks | tasks:edit | Allows users to edit their tasks. |
| View tasks | tasks:view | Allows users to view tasks. |
There are also two custom roles created, and the Member role is updated to include the `View tasks` and `Edit tasks` permissions:
| Name | Key | Description | Permissions |
| -------- | ------- | --------------------------------------------------------------- | -------------------------------------------------- |
| Manager | manager | Users with this role can create tasks and edit all tasks. | View tasks, Edit tasks, Manage tasks, Read Members |
| Member\* | member | Users with this role can create tasks and edit their own tasks. | View tasks, Edit tasks, Read members |
| Viewer | viewer | Users with this role can only view tasks. | View tasks, Read members |
- The Member role is a default role.
Now when a user is invited, administrators can set their role even before they accept the invitation.
## Adjusting functionality based on permissions
A role defines a set of permissions, but the permissions themselves should dictate what parts of the application users within that role have access to.
Clerk provides [a set of authorization helper functions](/blog/introducing-authorization) that can be used to check if the active user has a specific set of permissions and appropriately adjust the way the application behaves. The following example demonstrates how the `has()` function can be used with the name of the permission to determine if the user can create or edit tasks:
```ts {{ filename: 'src/app/security.ts' }}
import { auth } from '@clerk/nextjs/server'
export function canCreateTasks() {
const { sessionClaims, has } = auth()
if (!isLicensed()) return false
let canCreateTasks = false
// 👉 If there is no org, it's the user's personal account
if (!sessionClaims?.org_id) {
canCreateTasks = true
}
// 👉 Check to make sure the user has the 'org:tasks:edit' permission
if (sessionClaims?.org_id && has({ permission: 'org:tasks:edit' })) {
canCreateTasks = true
}
return canCreateTasks
}
export function canEditTask(createdById: string) {
if (!isLicensed()) return false
const { userId, sessionClaims, has } = auth()
let canEditTask = false
// 👉 If there is no org, it's the user's personal account
if (!sessionClaims?.org_id) {
canEditTask = true
} else {
// 👉 If the user has the 'org:tasks:manage' permission, they can edit any task
if (has({ permission: 'org:tasks:manage' })) {
canEditTask = true
// 👉 If the user has the 'org:tasks:edit' permission AND the user IDs match, they can edit this task
} else if (has({ permission: 'org:tasks:edit' }) && createdById === userId) {
canEditTask = true
}
}
return canEditTask
}
```
These security functions are passed into the rendered components to determine if they should be disabled:
```tsx {{ filename: 'src/app/page.tsx' }}
{tasks.map((task) => (
))}
```
The security functions can also be used to verify user's permissions in server actions. The following function is executed when the user wants to create a task. By leveraging the `canCreateTasks()` function, an erorr is thrown if the user attempts to do something they are not permitted to do:
```ts {{ filename: 'src/app/actions.ts' }}
import { canCreateTasks, getUserInfo } from './security'
export async function createTask(name: string) {
if (!canCreateTasks()) {
throw new Error('User not permitted to create tasks')
}
const { userId, ownerId } = getUserInfo()
await sql`
insert into tasks (name, owner_id, created_by_id) values (${name}, ${ownerId}, ${userId});
`
}
```
## Working directly with roles and permissions
While Clerk offers a simple way to check the active user's permissions out of the box, there may be a situation where you want to check their roles or permissions manually.
By default, a user's organizational permissions can be accessed through the `sessionClaims` object of the `auth()` function:
```ts
const { sessionClaims } = auth()
```
This gives you the flexibility to leverage the roles and permissions as you see fit. The following sample shows the structure of the `sessionClaims` if a user has selected an organization:
```json
{
"azp": "http://localhost:3005",
"exp": 1721770193,
"iat": 1721770133,
"iss": "https://assuring-cod-50.clerk.accounts.dev",
"jti": "daeb648e4c6dbfbdd2ce",
"nbf": 1721770123,
"org_id": "org_2ieWEfZl0M6ccS1Ap1XVRbEm9Kk",
"org_metadata": {
"isLicensed": true
},
"org_permissions": ["org:tasks:edit", "org:tasks:view", "org:tasks:manage"],
"org_role": "org:manager",
"org_slug": "d2-gamers",
"sid": "sess_2jfFHBJQpqzwZbnwHXti0yxCz1G",
"sub": "user_2iVvo8iFCJQJ1WCXeBk5T9lUTO5"
}
```
## Conclusion
With minimal effort, role-based access control is made accessible to applications of any size using organizations in Clerk. By checking the list of permissions a user has based on their assigned role, you can easily enable different areas of your application, or restrict functionality.
---
# Mitigating OAuth’s recently discovered Open Response Type vulnerability
URL: https://clerk.com/blog/open-response-type-vulnerability.md
Date: 2024-08-07
Category: Company
Description: How Clerk mitigated the recently discovered Open Response Type vulnerability
On July 29, security researchers at Salt [released details](https://salt.security/blog/over-1-million-websites-are-at-risk-of-sensitive-information-leakage---xss-is-dead-long-live-xss)
of an OAuth vulnerability that can reliably be chained with any XSS vulnerability
to establish a long-lived account takeover. This is a general OAuth vulnerability, not particular to Clerk’s implementation.
At Clerk, we believe it’s our responsibility to protect our customers from vulnerabilities
like this, so we worked quickly to understand the attack and devise a mitigation.
Fortunately, we discovered that **Clerk’s default configuration is not susceptible to this
chaining, and over 99.7% of our customers were already protected.** For the last 0.3%, we
released an update today that mitigates the attack.
In this post, we dive into the technical details of the vulnerability, why most customers were protected by default, and how we mitigated the attack for the last few.
## Understanding the Open Response Type vulnerability: a clever variation of the Open Redirect
### The OAuth happy path
The OAuth flow starts by redirecting a user to the “authorization URL” of an identity
provider, with `redirect_uri` and `response_type` in the query param, as well as an application identifier and the scope of authorization requested. Here’s a sample for Google:
```plaintext {{ mark: [2] }}
https://accounts.google.com/o/oauth2/auth
?redirect_uri=https%3A%2F%2Fmyapp.com%2Foauth_callback
&response_type=code
&client_id={oauth_client_id}
&scope={requested_authorization_scopes}
```
On Google’s website, the user is asked to authorize the requested scope, which
normally only includes profile information so the user can be signedin.
After authorization, the user is redirected back to the `redirect_uri` using
the given `response_type`. In this case, the response type is `code`, which means
a single-use secret code is appended to the `redirect_uri` as a query param:
```
https://myapp.com/oauth_callback?code={secret_code}
```
### The Open Redirect vulnerability
An “Open Redirect” is when an attacker tricks a user into visiting an
authorization URL with a nefarious value passed to `redirect_uri`.
For example, instead of passing `https://myapp.com/oauth_callback`,
they can pass `https://attackapp.com/oauth_callback`. This accomplishes two things:
1. `https://myapp.com/oauth_callback` doesn’t receive the secret code,
so its single-use nature does not provide any protection.
2. The attacker gets access to a secret code. With it, they can open
a new browser on their own machine, and navigate to the valid `redirect_uri`
with the code appended. This tricks the application into granting a
session for the victim to the attacker.
Thankfully, the OAuth specification guides implmentors on how to prevent Open Redirects, and Google and
other identity providers maintain a strict allowlist of acceptable `redirect_uri`s. The allowlist ensures that
the user, *and the secret code,* will not be sent to a URL the attacker controls.
### The Open Response Type vulnerability
In OAuth, the response type dictates the format and mechanism for how
the identity provider passes sensitive information back to the application.
With `code`, a single-use token is passed by query param.
With `token`, an access token is passed by the URL’s hash fragment.
Unlike `redirect_uri`s, the `response_type` parameter is not strictly
bound to a per-application allowlist. This lack of enforcement is pivotal
to the attack, which is why we’re calling it the “Open Response Type”
vulnerability. Here is [Salt’s explanation](https://salt.security/blog/over-1-million-websites-are-at-risk-of-sensitive-information-leakage---xss-is-dead-long-live-xss) of how the parameter was leveraged:
> Note that we changed the original OAuth link to Google - we used the response
> type “code,token” instead of only “code”, which makes Google send the code in
> the hash fragment (#code=...). This enables us to read the code from the URL
> and ensure Hotjar doesn’t consume the code, which can be consumed only once.
After changing the response type to `code,token`, the secret code is returned
in the fragment instead of the query param. In all likelihood, the application
implementing OAuth has not prepared for a secret code to be in the fragment,
so it doesn’t consume it, and it remains in the URL instead.
Put another way: the open nature of `response_type` means an attacker has a
reliable way to get a valid, unused secret code in the URL bar.
Thankfully, getting the code in the URL bar alone is not sufficient, since the
attacker also must be able to read its value. This is not normally possible,
but it is when an XSS vulnerability is present. Depending on the page the XSS
is present on, it may be as easy as reading `window.location.href`.
In Salt’s case, they opened a new tab to the Authorization URL via `window.open`,
then polled the tab’s `location` until the OAuth flow completed.
### The impact
You might be wondering: **Do we really need to worry about Open Response Type
if it needs to be chained with an XSS attack?**
The answer is **absolutely yes**. When managing user sessions on the web, it’s
critical to mitigate the effects of XSS as much as possible. After an XSS is
patched, it should be impossible for the attacker to continue acting on behalf
of any users.
This is why developers use the `HttpOnly` directive when managing session cookies:
it ensures that session tokens cannot be extracted for the attacker to continue
using after the XSS is patched. Without this feature, developers would need to
revoke sessions after an XSS attack and force users to sign in again.
The challenge with the Open Response Type vulnerability is that it completely
bypasses the protections afforded by `HttpOnly`. The attacker is able to generate
new sessions, and those sessions will continue to be valid after the XSS is patched.
## Mitigating the Open Response Type vulnerability
The Open Response Type vulnerability relies on two behaviors:
1. The user must land on a page with an unused code in the URL bar.
2. The application must have an open XSS vulnerability that allows them to
programmatically read the URL bar.
Below, we list two techniques that can be used to suppress these behaviors.
### Mitigation 1: Process the OAuth code on a separate origin
At the top of this post, we mentioned that over 99.7% of Clerk customers
were protected by default. That is because Clerk forces developers to set
the OAuth `redirect_uri` to be an endpoint on our API, which is normally
hosted on a subdomain like `https://clerk.yourdomain.com`. When the Open
Response Type attack is attempted against a Clerk customer, the user would
land on URL on this subdomain, like:
```
https://clerk.yourdomain.com/v1/oauth_callback#code={secret_code}
```
Fortunately, this subdomain does not serve HTML, so it’s exceedingly unlikely
to be the source of an XSS. An XSS on any other subdomain cannot read the URL
of a tab on the Clerk subdomain, since it breaks the web’s cross-origin rules.
If your application also leverages a separate origin for processing the OAuth
code (e.g. `identity.yourdomain.com` or `auth.yourdomain.com`), it will also
be protected as long as that origin never introduces an XSS.
While this technique helps, it’s hard to guarantee that you will never introduce
an XSS on the origin processing the OAuth code. For that reason, we recommend
using Mitigation 2 instead.
### Mitigation 2: Eliminate unexpected fragments
Some Clerk customers use a reverse proxy to host our API directly on their
primary domain, so OAuth codes are not processed on a separate origin. For
these users, and for a more robust solution overall, we needed to find an
additional mitigation.
Our solution is to eliminate unexpected fragments from the URL bar before
an XSS vulnerability has the chance to read them. To do this, we’ve added an extra redirect to any OAuth failure that eliminates
the fragment.
Again, let’s consider a user that lands on this URL as a result of an Open
Response Type attack:
```
https://clerk.yourdomain.com/v1/oauth_callback#code={secret_code}
```
Fragments aren’t sent to the server, so our server cannot tell that `code`
is even present. But, this URL is expecting `code` in the query param, and
since it’s missing, Clerk is going to return an error.
Instead of simply returning the error, we are now issuing a redirect first.
We issue the redirect with status=301 and a Location header that has a
trailing #, which clears any fragment that might exist:
```
Location: https://clerk.yourdomain.com/v1/oauth_callback#
```
Since we use Clerk at Clerk, you can confirm the behavior by visiting the
URL on our domain with a fake code – the code will be stripped away.
(You’ll notice we add an extra query param to prevent an infinite redirect.)
```
https://clerk.clerk.com/v1/oauth_callback#code=fakerandomcode
```
This behavior is easy to implement in your own OAuth handler and will
effectively protect you against Open Response Type attacks.
---
# Per-user B2B monetization with Stripe and Clerk Organizations
URL: https://clerk.com/blog/per-user-licensing-with-stripe-and-clerk-organizations.md
Date: 2024-08-02
Category: Guides
Description: Learn how to architect a B2B application for per-user licensing with Stripe and Clerk Organizations
Businesses tend to spend more money on software compared to individual consumers.
One of the most popular monetization models for B2B applications is the Per-User model, where a business purchases one “seat” for each user who will be using the application. Per-user pricing is a great way for application developers to generate income. The model is relatively straightforward, provides predictable pricing for finance departments, and allows for a steady stream of income that scales with the use of your application
In this article, you'll learn how Clerk Organizations and Stripe can be configured to implement per-user monetization into a web application.
> This guide focuses on implementation details. For a comprehensive overview of B2B SaaS architecture and features, [learn more about our B2B SaaS solution](/b2b-saas).
## Project Overview
This article will use an open-source application called Team Task that is preconfigured with the functionality described below. All of the critical parts of the code that enable per-user licensing will be thoroughly explained, however, you are welcome to dive right into the [code hosted in GitHub](https://github.com/bmorrisondev/team-todo-demo/tree/article-2).
Everything is built with self-service in mind, so users will be able to do the following without assistance from you:
- Create organizations and invite users
- Add and manage licenses using Stripe
- Assign and remove licenses from individual users
Using the pre-built Clerk components, users will be able to create organizations and invite users.
Once the organization is created, they will be prompted to purchase licenses via Stripe. Once purchased, administrators can toggle users to gain full use of the application.
Finally, administrators will also be able to easily manage their Stripe subscription with the click of a button.
## Creating organizations
Clerk Organizations allows you to easily add multi-tenancy into an application by letting users create organizations and invite users into them using the `OrganizationSwitcher` component.
When a user creates an organization, they'll immediately be asked if there are any users they want to invite into the organization by simply providing a list of email addresses. Behind the scenes, our system will also check to see if the Clerk application has any endpoints that are configured to receive a webhook when an organization is created.
Webhooks are a way for one service to inform another when an event occurs. The event, in this case, was that an organization was created. Team Task contains a route handler at `/api/clerk-hooks` that is configured to accept the following payload that Clerk will send when an organization is created:
```json
{
"data": {
"admin_delete_enabled": true,
"created_at": 1721316613833,
"created_by": "user_2iNu3heTeGj0U8G2gGFPWnVLbZm",
"has_image": false,
"id": "org_2jQQ2U3ykrhcoElPbh6ZVgUPKlV",
"image_url": "https://img.clerk.com/eyJ0eXBlIjoiZGVmYXVsdCIsImlpZCI6Imluc18yaU50WjRDSGh2V1UwUW14bzYzZE81S3NNRjIiLCJyaWQiOiJvcmdfMmpRUTJVM3lrcmhjb0VsUGJoNlpWZ1VQS2xWIiwiaW5pdGlhbHMiOiJEIn0",
"logo_url": null,
"max_allowed_memberships": 5,
"name": "Dev Ed",
"object": "organization",
"private_metadata": {},
"public_metadata": {},
"slug": "dev-ed",
"updated_at": 1721316613833
},
"event_attributes": {
"http_request": {
"client_ip": "73.36.196.123",
"user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/126.0.0.0 Safari/537.36"
}
},
"object": "event",
"type": "organization.created"
}
```
To automate the process of creating Stripe customer records based on organizations in the application, we can accept the webhook message, create a Stripe customer, and create a record in a Neon table to associate the Clerk `org_id` to the Stripe `customer_id`.
```tsx {{ filename: 'src/app/api/clerk-hooks/route.ts' }}
const stripe = new Stripe(process.env.STRIPE_KEY as string)
const sql = neon(process.env.DATABASE_URL as string)
const handler = createWebhooksHandler({
secret: process.env.CLERK_WEBHOOK_SECRET as string,
onOrganizationCreated: async (org) => {
// Create customer in Stripe
const customer = await stripe.customers.create({
name: org.name,
})
// Create record in neon
await sql`insert into orgs (org_id, stripe_customer_id) values (${org.id}, ${customer.id})`
},
})
```
This table will also track the number of licenses an organization has purchased, using a default value of `0` when the record is created.
### Process overview
1. A user starts the process by creating an organization in Clerk.
2. Clerk's backend will asynchronously send a message to a route handler informing the application that a new organization was created.
3. The application will create a customer in Stripe.
4. Finally, the application will insert a new row into a Neon database to associate the Clerk Organization with the Stripe Customer, along with a default license count of 0.
## Initial license purchase
Once the organization is created and users are invited, we'll redirect the current user to a page that lets them purchase licenses for the organization.
The `OrganizationSwitcher` uses the `afterCreateOrganizationUrl` prop to automatically forward the user to the `/licensing` page.
```tsx {{ filename: 'src/components/navbar.tsx' }}
```
The licensing page is used for both the initial license purchase as well as managing and allocating licesnes over time. When the page is loading, it queries the `license_count` value in the `orgs` table for that organization to determine how to render the page.
```tsx {{ filename: 'src/app/licensing/page.tsx' }}
{currentLicenseCount === 0 ? (
) : (
)}
```
The `PurchaseLicensesCard` component displays an input for the user to select how many licenses are required. Selecting the **"Purchase via Stripe"** button will use that value to create a Stripe Checkout Session using a server action.
Creating a Checkout Session requires the customer ID, a product ID that represents the per-user rate, purchase quantity, and redirect URLs. The session object returned from Stripe will contain the `url` that the user should be sent to for completing the transaction.
```tsx {{ filename: 'src/app/licensing/actions.ts' }}
export async function getCheckoutUrl(clerkOrgId: string, quantity: number) {
const [row] = await sql`select stripe_customer_id from orgs where org_id=${clerkOrgId}`
const session = await stripe.checkout.sessions.create({
mode: 'subscription',
customer: row.stripe_customer_id,
line_items: [
{
price: 'price_1PajlBGVJ29rMAV1JmqqgEwa',
quantity: quantity,
adjustable_quantity: {
enabled: true,
minimum: 1,
},
},
],
success_url: 'http://localhost:3005/licensing',
cancel_url: 'http://localhost:3005/licensing',
})
return session.url
}
```
Since the `PurchaseLicensesCard` is a client component, we can redirect them using `window.location.href`:
```tsx {{ filename: 'src/app/licensing/PurchaseLicensesCard.tsx' }}
async function onPurchaseClicked() {
setIsLoading(true)
const url = await getCheckoutUrl(organization?.id as string, count)
window.location.href = url as string
}
```
The user will then be prompted for payment info to complete the transaction.
After payment, they'll be redirected back to `/licensing`, where a list of users will be displayed to allocate licenses to.
Stripe offers webhooks for a wide array of events that occur on their end as well. The `customer.subscription.created` webhooks can be used to update the `license_count` value of an organization in the Neon database to match the value that was purchased:
```tsx {{ filename: 'src/app/api/stripe-hooks/route.ts' }}
export async function updateLicenseCount(stripeCustomerId: string, quantity: number) {
const sql = neon(process.env.DATABASE_URL as string)
await sql`update orgs set license_count=${quantity} where stripe_customer_id=${stripeCustomerId}`
}
export async function POST(request: NextRequest) {
const sig = request.headers.get('stripe-signature')
const body = await request.text()
const event = stripe.webhooks.constructEvent(body, sig, endpointSecret)
// Handle the event
switch (event.type) {
case 'customer.subscription.created':
await updateLicenseCount(
event.data.object.customer as string,
// @ts-ignore
event.data.object.quantity,
)
break
default:
console.log(`Unhandled event type ${event.type}`)
}
return new NextResponse(null, { status: 200 })
}
```
### Process overview
1. The user provides the number of licenses to purchase, and the application requests a Checkout Session URL from Stripe.
2. The user is sent to Stripe to complete the transaction.
3. Stripe will redirect the user back to the application URL while simultaneously sending an asynchronous webhook message to a route handler of the application.
4. The application will update the `license_count` value for that organization in the Neon database.
## Licensing users
Now that licenses have been purchased, they need to be assigned to users.
As mentioned in the previous section, the `/licensing` page will automatically be updated to render a list of users who are members of an organization by querying the `license_count` value on load.
Since individual users can have access to multiple organizations within a single Clerk application, we use the concept of a “membership” to associate a user to an organization, modeling what is effectively a “many to many” relationship:
Clerk offers various types of metadata to add arbitrary data to entities in Clerk, and memberships can also contain metadata independent of the organization or user. Toggling on the last column will flag the user as “licensed” in their membership metadata using the following server action:
```tsx {{ filename: 'src/app/licensing/actions.ts' }}
export async function toggleUserLicense(orgId: string, userId: string, status: boolean) {
await clerkClient.organizations.updateOrganizationMembershipMetadata({
organizationId: orgId,
userId: userId,
publicMetadata: {
isLicensed: status,
},
})
}
```
When the licensing page loads, the Clerk Backend API is used to query the memberships of the organization, which includes the metadata used to flag a specific user as licensed in that organization. This both sets the toggle for the user row as well as to aggregate the total number of currently licensed users, which will also be used to determine how many licenses are available.
```tsx {{ filename: 'src/app/licensing/page.tsx' }}
const [row] =
await sql`select license_count from orgs where org_id=${sessionClaims?.org_id as string}`
const currentLicenseCount = row.license_count
let currentlyLicensedUsers = 0
// Load users
let res = await clerkClient.organizations.getOrganizationMembershipList({
organizationId: sessionClaims?.org_id as string,
})
const users: UserRowViewModel[] = []
res.data.forEach((el) => {
let name = el.publicUserData?.firstName
? `${el.publicUserData?.firstName} ${el.publicUserData?.lastName}`
: ''
const isLicensed = (el.publicMetadata?.isLicensed as boolean) || false
if (isLicensed) {
currentlyLicensedUsers++
}
users.push({
id: el.publicUserData?.userId as string,
orgId: sessionClaims?.org_id as string,
email: el.publicUserData?.identifier as string,
name: name,
isLicensed,
})
})
```
If the `currentlyLicensedUsers` value is equal or greater than `currentLicenseCount` and the user is not already licensed, the ability to enable licenses for a user can be disabled:
```tsx {{ filename: 'src/app/licensing/page.tsx' }}
{users?.map((u) => (
= currentLicenseCount}
/>
))}
```
## Managing the subscription
Besides rendering a list of users, the `/licensing` page now also renders the `ManageLicensesCard` component to display the available of licenses along with a button to manage the current subscription using the Stripe Customer Portal.
The [Customer Portal](https://docs.stripe.com/customer-management) is a hosted solution from Stripe that allows users to manage their own subscriptions without developers having to build a custom user interface.
This feature is off by default, but can easily be enabled in the [Stripe Dashboard](https://dashboard.stripe.com/test/settings/billing/portal). Since licenses are managed via Stripe subscriptions, we only need to allow subscription management for our customers for this specific SKU.
As with the Checkout Session for the initial license purchase, a custom URL will be generated based on the Stripe customer ID:
```tsx {{ filename: 'src/app/licensing/actions.ts' }}
export async function getPortalUrl(clerkOrgId: string) {
const stripeId = await getStripeCustomerIdFromOrgId(clerkOrgId)
const session = await stripe.billingPortal.sessions.create({
customer: stripeId,
return_url: 'http://localhost:3005/licensing',
})
return session.url
}
```
After the URL is returned to the front end, the user will be redirected to the Customer Portal where they can adjust their licenses as needed:
The `customer.subscription.updated` event from Stripe will also be handled in the route handler to update the license count for a specific organization:
```tsx {{ filename: 'src/app/api/stripe-hooks/route.ts', prettier: false }}
case 'customer.subscription.updated':
await updateLicenseCount(
event.data.object.customer as string,
// @ts-ignore
event.data.object.quantity,
)
break
```
### Process overview
1. The application generates a Customer Portal URL from Stripe for the active customer.
2. The user can manage the number of licenses active in their subscription.
3. Upon updating the subscription, Stripe sends a webhook to the application informing it of the change.
4. The application updates the `license_count` in the database.
## Accessing license status
Clerk makes it easy to access information about the currently logged-in user, and accessing membership metadata is no exception.
Recall that we stored the `isLicensed` flag within the membership metadata. To access these values, the `sessionClaims` object of the `auth()` function can be used:
```tsx {{ filename: 'src/app/page.tsx' }}
const { sessionClaims } = auth()
let isLicensed = false
if (sessionClaims?.org_metadata && sessionClaims?.org_metadata.isLicensed) {
isLicensed = true
}
```
Then you can decide what functionality of the application can be restricted based on that flag, for example:
```tsx {{ filename: 'src/app/page.tsx', prettier: false }}
{tasks.map((task) => )}
```
## Summary
Per-user licensing is a great way to monetize an application. Stripe offers a great suite of tools that allows developers to process transactions and generate revenue from their work. By combining with power of Clerk Organizations with Stripe, you can build a seamless workflow for your users to independently create their own tenants, purchase and assign licenses for those tenants, and change the subscription at any time.
---
# Build a team-based task manager with Next.js, Neon, and Clerk
URL: https://clerk.com/blog/build-a-team-based-task-manager-with-organizations.md
Date: 2024-07-09
Category: Guides
Description: Use Clerk Organizations to build a task management app that isolates tasks to specific teams.
Building a multi-tenant application with robust permissions can be tricky.
Clerk Organizations were designed to simplify adding multi-tenant functionality to your application. By implementing Organizations, your users will be empowered to create isolated areas of your application, while also allowing users to have granular permissions based on their assigned roles, restricting or permitting functionality as needed.
> Organizations are a core feature of B2B applications. [Learn more about our B2B SaaS solution](/b2b-saas) for comprehensive multi-tenant architecture.
In this article, we'll take leverage the common example of a to-do app and implement Clerk Organizations to enable users to access task lists that are shared across teams.
## Project overview and setup
This guide uses an open-source starter project that you can clone to your computer to build on.
The project is a multi-tenant take on a simple concept; a task management app. Upon setting up the project, you'll have a functional to-do app where you can add, complete, and update tasks. Throughout this guide, you'll add the ability to create and switch between organizations, where each organization has an isolated list of tasks where multiple users can be invited into for collaboration.
To follow along, this guide assumes you have a general understanding of Next.js as well as [Node and NPM installed locally](https://nodejs.org/en/download/package-manager) on your workstation.
### Clone the project locally
To follow this guide, open your terminal and clone the starter repository using the following script. This will also switch you to the `article-1` branch which contains the proper starting point for this article:
```bash
git clone https://github.com/bmorrisondev/team-todo-demo.git
git checkout article-1
```
Now run the following script in your terminal to install the necessary dependencies.
```bash
npm install
```
### Set up a Clerk project
If you do not have a Clerk account, create one before proceeding, which will walk you through creating a project. If you already have an account, create a new project for this guide. Give the project a name and accept the default login providers: Email and Google.
You'll be presented with a Next.js quick start guide. Follow only step 2, which instructs you to create the `.env.local` file and populate it with the necessary environment variables. The remainder of the steps are already completed as part of the starter repo.
### Set up a Neon database
While any Postgres database should be usable, this guide leverages Neon. If you do not have an account, create one at neon.tech. If you do, create an empty database, copy the connection string from the “**Connection Details**” block, and add it to your `.env.local` file as `DATABASE_URL` like so:
```bash
DATABASE_URL=postgresql://teamtodo_owner:*********@ep-frosty-tree-a54nb30r.us-east-2.aws.neon.tech/teamtodo?sslmode=require
```
Next, access the SQL Editor from the left navigation and paste in the following database script to set up the schema:
```sql
create table tasks (
id serial primary key,
name text not null,
description text,
is_done boolean not null default false,
owner_id text not null,
created_on timestamp not null default now(),
created_by_id text not null
);
```
### Access the project
Back on your computer, start the project with the following command:
```bash
npm run dev
```
By default, the application will be accessible at [`http://localhost:3000`](http://localhost:3000) however the port might be different if another process is using port 3000, so use what's shown in the terminal. Accessing the URL from your browser should prompt you to create an account using Clerk before rendering this:
Feel free to test it out by adding a few tasks.
## Enable Clerk Organizations
Now that you understand the project and the current state it's in, let's start by setting up the Organizations feature in Clerk.
Log into the Clerk Dashboard and select **"Organization Settings"** from the left navigation. In the settings tab, click the toggle next to **"Enable organizations"** if it's not on already.
From now on, users within this Clerk application will be able to create organizations and invite other users to them. This setting is configurable on this same page. Make sure to leave the default checked for the remainder of this guide.
## Update the code
Now that Clerk Organizations are set up, we need to update the project to enable users to create organizations, switch between them, and create tasks specifically for that organization.
Start by adding the `OrganizationSwitcher` to the `Navbar` component:
```ts {{ filename: 'src/app/layout/Navbar.tsx', del: [3], ins: [4, 15] }}
import * as React from 'react'
import Link from 'next/link'
import { SignedIn, SignedOut, UserButton } from '@clerk/nextjs'
import { OrganizationSwitcher, SignedIn, SignedOut, UserButton } from '@clerk/nextjs'
import { metadata } from '@/app/layout'
function Navbar() {
return (
)
}
export default Navbar
```
The application should update to show “**Personal account**” next to your avatar in the upper right. This essentially indicates that the user does not have an organization selected that they are working in.
This same menu gives you the ability to create an organization, however, the database queries will need to be modified to recognize that the user is in an organization, so let's get those updated now.
The `auth()` function, part of Clerk's Next.js SDK, returns token claims for the current user stored in `sessionClaims`. These claims can be used to determine if an organization is selected along with the permissions the user has set for that specific organization. By default the `org_id` value of the claims is not set unless the user has an organization selected, indicating they are in the “Personal account”.
The following is what `sessionClaims` looks like with an organization selected:
```tsx {{ prettier: false }}
{
exp: 1719602340,
iat: 1719602280,
iss: 'https://assuring-cod-50.clerk.accounts.dev',
jti: '3194d5c953057b24c256',
nbf: 1719602270,
org_id: 'org_2iR0dJJzzY3q9kLK0gsDVT08IP4',
org_role: 'org:admin',
org_slug: 'd2-gamers',
sid: 'sess_2iWNGtu9GSFzttofPmhfB23FL9q',
sub: 'user_2iNu3heTeGj0U8G2gGFPWnVLbZm',
}
```
Currently, the `getUserInfo` function in `src/app/actions.ts` uses the `auth()` function to return the user's ID from the claims, which is used as the `owner_id` in the database for a given task. The following snippet shows `getUserInfo` updated to conditionally return `org_id` if it is populated and how it is used in the database queries.
Note however that `userId` is still being used to maintain a record of who creates specific tasks, regardless if an organization is set or not.
```tsx {{ filename: 'src/app/actions.ts', ins: [18, [21, 23], 30, 34, 41, 45, 51, 55, 61, 65], del: [29, 33, 40, 44, 50, 54, 60, 64] }}
'use server'
import { auth } from '@clerk/nextjs/server'
import { neon } from '@neondatabase/serverless'
if (!process.env.DATABASE_URL) {
throw new Error('DATABASE_URL is missing')
}
const sql = neon(process.env.DATABASE_URL)
function getUserInfo() {
const { sessionClaims } = auth()
if (!sessionClaims) {
throw new Error('No session claims')
}
let userInfo = {
userId: sessionClaims.sub,
ownerId: sessionClaims.sub,
}
if (sessionClaims.org_id) {
userInfo.ownerId = sessionClaims.org_id
}
return userInfo
}
export async function getTasks() {
const { userId } = getUserInfo()
const { ownerId } = getUserInfo()
let res = await sql`
select * from tasks
where owner_id = ${userId};
where owner_id = ${ownerId};
`
return res
}
export async function createTask(name: string) {
const { userId } = getUserInfo()
const { userId, ownerId } = getUserInfo()
await sql`
insert into tasks (name, owner_id, created_by_id)
values (${name}, ${userId}, ${userId});
values (${name}, ${ownerId}, ${userId});
`
}
export async function setTaskState(taskId: number, isDone: boolean) {
const { userId } = getUserInfo()
const { ownerId } = getUserInfo()
await sql`
update tasks set is_done = ${isDone}
where id = ${taskId} and owner_id = ${userId};
where id = ${taskId} and owner_id = ${ownerId};
`
}
export async function updateTask(taskId: number, name: string, description: string) {
const { userId } = getUserInfo()
const { ownerId } = getUserInfo()
await sql`
update tasks set name = ${name}, description = ${description}
where id = ${taskId} and owner_id = ${userId};
where id = ${taskId} and owner_id = ${ownerId};
`
}
```
## Test Organization lists
To test the changes, use the Organization Switcher from the navigation bar and create a new organization.
The task list should automatically refresh into a blank list. Create a task to make sure it gets added to the list. Now switch back to the “Personal account” organization and notice how your previous list of tasks is rendered without the task you created while the organization was selected.
Now let's invite another user into the organization to demonstrate how the tasks in the organization are shared, but the “Personal account” tasks are isolated between users.
If you are in the “Personal account” still, use the switcher to select the organization you created. Once active, use the switcher again and click the gear icon next to the organization name. Then select Members from the left navigation in the modal, and finally click the “Invite” button. Invite another user via their email address.
Many email providers support [plus notation](https://gmail.googleblog.com/2008/03/2-hidden-ways-to-get-more-from-your.html) where you can add a + to the end of your username along with an identifier to create a separate email address.
This can be used if you do not have multiple email addresses.
The user should receive an email with an invitation to the organization. Accept the invitation and create an account with the application. Upon completing the sign-up process, you should be dropped into the “Personal account” of the new user, which will have a blank list of tasks.
Now use the Organization Switcher to select your organization to see the tasks created by the previous user.
Adding additional tasks will show them for all users that have access to this organization.
## Conclusion
Clerk Organizations feature provides a way to easily add multi-tenancy into your application.
In this article, you learned how Organizations can be used to allow users to add and modify data across available organizations. By enabling Organizations and slightly tweaking the code based on the token claims, your applications can take advantage of isolated, collaborative environments just like the demo app that was built onto in this guide.
If you enjoyed this article, share it on X and let us know what you liked about it by tagging [@clerk](https://x.com/clerk)!
---
# Building a Hybrid Sign-Up/Subscribe Form with Stripe Elements
URL: https://clerk.com/blog/building-a-hybrid-sign-up-and-subscribe-form-with-stripe.md
Date: 2024-06-18
Category: Guides
Description: Using custom flows, webhooks, and user metadata, learn how to build a single form that automatically subscribes new users.
I had a user reach out to me on X asking if there was any way to integrate a Stripe credit card entry field with Clerk's sign-up forms.
Can you actually create a sign up + card details input in a single page when using @clerk?
Using the OTP method.
Kostas is building a Chrome extension that uses AI to let users write responses to LinkedIn posts directly from their browser. To reduce the friction of users who want to sign up for the trial, he presented the following requirements:
1. It should be a single form that accepts an email address, tier selection, and credit card details.
2. The user should complete the sign-up using a one-time passcode sent to their email account.
3. Upon verifying their email, the user should automatically be signed up for a trial of the selected tier with no further interaction.
In this article, I'll walk through the process of building a completely custom sign-up form that matches the above requirements, starting with the end result.
## The final product
Before walking through how this solution was built, it's worth seeing it in action. The first phase of the signup process has the user entering the details outlined above.
Upon completing this form, the user receives an email from Clerk with their sign-up code. The form in the previous screenshot will automatically update to accept a verification code.
After the code is entered, the user is presented with a loading view, indicating that their account is being created in Clerk and the subscription is being registered in Stripe. Although the user experience appears seamless, the process happening behind the scenes is rather complex with a number of moving parts. Let's explore how this solution was built, starting with the front-end part.
## Constructing the form
We'll start by exploring the components of both Clerk and Stripe that are used to build the user-facing part of this flow.
### Custom flows
Clerk has a great set of predesigned components that developers can drop directly into their application to provide a great sign-up and sign-in experience for their users.
In this scenario, however, the default components are not flexible enough to embed a product selection and credit card form, so we'll need to use [Custom flows](/docs/custom-flows/overview). Custom flows in Clerk allow you to build custom forms with your own logic to both register and sign in users, as well as customize the logic behind these actions to do whatever you need to for your application. Instead of using any of the components, we can instead build an HTML `