User administration
Retrieve and manage application users through methods on the users resource.
Clerk · Function
clerkClient
clerkClient is a JavaScript wrapper around Clerk's Backend API. Instantiate it with createClerkClient({ secretKey }), then use resource methods such as users.getUserList().
How it works
clerkClient provides resource-oriented access to Clerk's Backend API from JavaScript environments. Create a client with createClerkClient({ secretKey }), then call methods on resources such as users and organizations; supported SDKs may also re-export a default instance.
Syntax
createClerkClient(options)Parameters
| Name | Type | Description |
|---|---|---|
options | CreateClerkClientOptions | Configuration object containing at least the Clerk Secret Key; additional options can customize the instance. |
Returns
A Clerk client instance exposing Backend API resources and their operations.
Key points
- It provides a higher-level JavaScript interface over Clerk's Backend API.
- The documented client is intended for JavaScript runtimes.
- Operations are grouped by domain resources, including users and organizations.
- Resources expose operations for actions such as creating, listing, and updating data.
- Framework SDKs may provide the client directly, so a separate backend import is not always necessary.
Common mistakes
- Do not call resource methods before creating or importing a client instance.
- A Secret Key is required when creating a custom client; keep it server-side.
Example: List users with a custom client
import { createClerkClient } from '@clerk/backend'
const clerkClient = createClerkClient({
secretKey: process.env.CLERK_SECRET_KEY,
})
const users = await clerkClient.users.getUserList()
console.log(users)Creates a server-side Clerk client with the Secret Key, then retrieves the application's users.
When to use it
Organization management
Work with organization-related Backend API operations through the organizations resource.
Backend API access
Replace hand-written requests to Clerk's Backend API with typed resource methods.
Interview questions
QWhat is clerkClient?
clerkClient is a wrapper around Clerk's Backend API for JavaScript environments. It exposes API resources such as Users and Organizations through methods like users.getUserList().
Follow-up: How would you avoid manually constructing Backend API requests? Use the corresponding resource method, because the SDK maps resource operations to Backend API functionality.
QHow do you instantiate a custom Clerk client?
Create a client with createClerkClient() and pass an options object containing the Clerk Secret Key. The resulting instance can be used to access resources such as users.
Follow-up: What configuration can accompany the Secret Key? The options object can include additional settings to customize the client behavior.
QWhen should you use a custom instance instead of the default client?
A custom client is useful when the application needs explicit configuration, while supported SDKs can re-export a default clerkClient. The default instance uses the CLERK_SECRET_KEY environment variable.
Follow-up: What is the alternative if the framework does not re-export the client? Install @clerk/backend and create the instance with createClerkClient().
Related
createClerkClientusers.getUserListusers.getUserorganizations