Users

To get started, it's important to first understand Clerk's User object.

The User object holds all of the information for a single user of your application and provides a set of methods to manage their account. Each User has at least one authentication identifier, which might be their email address, phone number, or a username.

A user can be contacted at their primary email address or primary phone number. They can have more than one registered email address, but only one of them will be their primary email address (User.primaryEmailAddress). This goes for phone numbers as well; a user can have more than one, but only one phone number will be their primary (User.primaryPhoneNumber). At the same time, a user can also have one or more external accounts by connecting to social providers such as Google, Apple, Facebook, and many more (User.externalAccounts).

Finally, a User object holds profile data like the user's name, profile picture, and a set of metadata that can be used internally to store arbitrary information. The metadata are split into publicMetadata and privateMetadata. Both types are set from the Backend API⁠, but public metadata can also be accessed from the Frontend API⁠.

For more information on the User object, such as helper methods for retrieving and updating user information and authentication status, see the reference docs. The User object is also available in the backend, but it looks slightly different. For more information, see the Backend User object reference docs.

Manage users

You can manage your users in the Clerk Dashboard, or in your app.

In the Clerk Dashboard

To manage users in the Clerk Dashboard, navigate to the Users⁠ page.

In your app

You can manage users in your app either through the frontend or backend.

In the frontend

Depending on the level of abstraction you need, you can manage users in the frontend using Clerk's prebuilt components, React hooks, or lower-level JavaScript methods.

• Prebuilt components: Clerk provides the prebuilt components <UserButton />
  and <UserProfile />
  to help your users manage their profile data.
• Hooks: Because Clerk's React-based SDKs are built on top of the Clerk React SDK, you can use the hooks that the React SDK provides. These hooks include access to the User object and helpful methods for managing user authentication and profile data.
• JavaScript methods: If Clerk's prebuilt components don't meet your specific needs or if you require more control over the logic, you can rebuild the existing Clerk flows using the Clerk API. For more information, see the custom flow guides.

In the backend

The JS Backend SDK exposes the Backend API⁠ resources and low-level authentication utilities for JavaScript environments.

There are many operations available for managing users, such as getUser(), createUser(), and deleteUser(). For more information, see the JS Backend SDK reference docs.

Create users

There are two ways to create users in Clerk: in the Clerk Dashboard or using the Backend API.

In the Clerk Dashboard

To create users in the Clerk Dashboard:

1. In the top in the Clerk Dashboard, select Users⁠.
2. Select Create user.
3. Enter the required user details and select Create.

Using the Backend API

You can create users in your app using Clerk's Backend API.

Use the following tabs to see examples of how to create users using one of the following:

• JS Backend SDK
• Express
• cURL

export async function POST() {
  try {
    const user = await clerkClient.users.createUser({
      emailAddress: ['test@example.com'],
      password: 'password',
    })
    return Response.json({ message: 'User created', user })
  } catch (error) {
    console.log(error)
    return Response.json({ error: 'Error creating user' })
  }
}

const client = await clerkClient()

const response = await client.users.createUser()

import { clerkClient } from '@clerk/express'

app.post('/createUser', async (req, res) => {
  const userData = req.body

  try {
    const user = await clerkClient.users.createUser(userData)
    res.status(200).json({ message: 'User created', user })
  } catch (error) {
    console.log(error)
    res.status(500).json({ error: 'Error creating user' })
  }
})

curl 'https://api.clerk.com/v1/users' -X POST -H 'Authorization:Bearer YOUR_SECRET_KEY' -H 'Content-Type:application/json' -d '{
  "email_address": ["test@example.com"],
  "password": "my-secure-password"
}'

Delete users

There are two ways to delete users in Clerk: in the Clerk Dashboard or using the Backend API.

In the Clerk Dashboard

To delete users in the Clerk Dashboard:

1. At the top of the Clerk Dashboard, select Users⁠.
2. You can either select the user and then in the side navigation menu, select Delete user, or select the menu icon on the right side of the user's row and select Delete user.

Using the Backend API

You can delete users in your app using Clerk's Backend API.

Use the following tabs to see examples of how to delete users using one of the following:

• JS Backend SDK
• Express
• cURL

export async function DELETE() {
  const userId = 'user_123'

  try {
    await clerkClient.users.deleteUser(userId)
    return Response.json({ message: 'User deleted' })
  } catch (error) {
    console.log(error)
    return Response.json({ error: 'Error deleting user' })
  }
}

const client = await clerkClient()

const response = await client.users.deleteUser(userId)

import { clerkClient } from '@clerk/express'

app.post('/deleteUser', async (req, res) => {
  const userId = req.body.userId

  try {
    await clerkClient.users.deleteUser(userId)
    res.status(200).json({ message: 'User deleted' })
  } catch (error) {
    console.log(error)
    res.status(500).json({ error: 'Error deleting user' })
  }
})

curl 'https://api.clerk.com/v1/users/{user_id}' -X DELETE -H 'Authorization:Bearer YOUR_SECRET_KEY' -H 'Content-Type:application/json'