Docs

JavaScript Backend SDK

Clerk's JavaScript Backend SDK exposes the Backend API resources and low-level authentication utilities for JavaScript environments.

For example, if you wanted to get a list of all users in your application, instead of creating a fetch to https://api.clerk.com/v1/users endpoint, you can use the users.getUserList() method provided by the JavaScript Backend SDK.

Installation

If you are using the JavaScript Backend SDK on its own, you can install it using the following command:

terminal
npm install @clerk/backend
terminal
yarn add @clerk/backend
terminal
pnpm add @clerk/backend

Clerk SDKs expose an instance of the JavaScript Backend SDK for use in server environments, so there is no need to install it separately.

Usage

All resource operations are mounted as sub-APIs on the clerkClient object. For example, if you would like to get a list of all of your application's users, you can use the getUserList() method on the users sub-API. You can find the full list of available sub-APIs and their methods in the sidebar.

To access a resource, you must first instantiate a clerkClient instance.

To instantiate a clerkClient instance, you must call createClerkClient() and pass in options.

Note

This example uses process.env to import environment variables. You may need to use an alternative method, such as import.meta.env, to set environment variables for your project.

import { createClerkClient } from '@clerk/backend'

const clerkClient = createClerkClient({ secretKey: process.env.CLERK_SECRET_KEY })

Instantiate a default clerkClient instance

You can use the default instance of clerkClient provided by whichever SDK you are using, and skip the need to pass configuration options, unless you are using Remix. For Remix, see the following section.

To use the default clerkClient instance, set your CLERK_SECRET_KEY environment variable and then import the clerkClient instance from the SDK as shown in the following example:

import { clerkClient } from '@clerk/nextjs/server'

If you are using Remix, see the following section for how to instantiate clerkClient.

import { clerkClient } from '@clerk/fastify'
import { clerkClient } from '@clerk/astro/server'
import { clerkClient } from '@clerk/express'

Instantiate a custom clerkClient instance

If you would like to customize the behavior of the JavaScript Backend SDK, you can instantiate a clerkClient instance yourself by calling createClerkClient() and passing in options.

import { createClerkClient } from '@clerk/nextjs/server'

const clerkClient = createClerkClient({ secretKey: process.env.CLERK_SECRET_KEY })

const userList = await clerkClient.users.getUserList()

If you are using Remix, you must instantiate clerkClient by calling the createClerkClient() function and passing in options.

import { createClerkClient } from '@clerk/remix/api.server'

Use the following tabs to see examples of how to use the Backend SDK in Remix Loader and Action functions.

routes/profile.tsx
import { LoaderFunction, redirect } from '@remix-run/node'
import { getAuth } from '@clerk/remix/ssr.server'
import { createClerkClient } from '@clerk/remix/api.server'

export const loader: LoaderFunction = async (args) => {
  // Use getAuth to retrieve user data
  const { userId } = await getAuth(args)

  // If there is no userId, then redirect to sign-in route
  if (!userId) {
    return redirect('/sign-in?redirect_url=' + args.request.url)
  }

  // Initialize clerkClient and perform the action,
  // which in this case is to get the user
  const user = await createClerkClient({ secretKey: process.env.CLERK_SECRET_KEY }).users.getUser(
    userId,
  )

  // Return the user
  return { serialisedUser: JSON.stringify(user) }
}
routes/profile.tsx
import { ActionFunction, redirect } from '@remix-run/node'
import { getAuth } from '@clerk/remix/ssr.server'
import { createClerkClient } from '@clerk/remix/api.server'

export const action: ActionFunction = async (args) => {
  // Use getAuth to retrieve user data
  const { userId } = await getAuth(args)

  // If there is no userId, then redirect to sign-in route
  if (!userId) {
    return redirect('/sign-in?redirect_url=' + args.request.url)
  }

  // Prepare the data for the mutation
  const params = { firstName: 'John', lastName: 'Wicker' }

  // Initialize clerkClient and perform the mutations
  const updatedUser = await createClerkClient({
    secretKey: process.env.CLERK_SECRET_KEY,
  }).users.updateUser(userId, params)

  // Return the updated user
  return { serialisedUser: JSON.stringify(updatedUser) }
}
import { createClerkClient } from '@clerk/fastify'

const clerkClient = createClerkClient({ secretKey: process.env.CLERK_SECRET_KEY })

const userList = await clerkClient.users.getUserList()

If you are using Astro, you must pass the endpoint context when invoking the clerkClient function.

import { clerkClient } from '@clerk/astro/server'

export async function GET(context) {
  const { userId, redirectToSignIn } = context.locals.auth()

  if (!userId) {
    return redirectToSignIn()
  }

  const user = await clerkClient(context).users.getUser(userId)

  return new Response(JSON.stringify({ user }))
}
app/routes/api/example.tsx
import { createClerkClient } from '@clerk/backend'
import { json } from '@tanstack/start'
import { createAPIFileRoute } from '@tanstack/start/api'

export const Route = createAPIFileRoute('/api/example')({
  GET: async ({ request, params }) => {
    const clerkClient = createClerkClient({ secretKey: import.meta.env.CLERK_SECRET_KEY })

    const userList = await clerkClient.users.getUserList()

    return json({ userList })
  },
})
import { createClerkClient } from '@clerk/express'

const clerkClient = createClerkClient({ secretKey: process.env.CLERK_SECRET_KEY })

const userList = await clerkClient.users.getUserList()
const Clerk = require('@clerk/express')

const clerkClient = Clerk.createClerkClient({ secretKey: process.env.CLERK_SECRET_KEY })

clerkClient.sessions
  .getSessionList()
  .then((sessions) => console.log(sessions))
  .catch((error) => console.error(error))

Error handling

Backend SDK functions throw errors (ClerkAPIResponseError) when something goes wrong. You'll need to catch them in a try/catch block and handle them gracefully. For example:

example.ts
try {
  const res = await someBackendApiCall()
} catch (error) {
  // Error handling
}

createClerkClient({ options })

The createClerkClient() function requires an options object. It is recommended to set these options as environment variables where possible, and then pass them to the function. For example, you can set the secretKey option using the CLERK_SECRET_KEY environment variable, and then pass it to the function like this: createClerkClient({ secretKey: process.env.CLERK_SECRET_KEY }).

The following options are available:

  • Name
    secretKey (required)
    Type
    string
    Description

    The Clerk secret key from the API Keys page in the Clerk Dashboard.

  • Name
    jwtKey?
    Type
    string
    Description

    The PEM public key from the API Keys page -> Show JWT public key -> PEM Public Key section of the Clerk Dashboard. For more information, refer to Manual JWT verification.

  • Name
    publishableKey?
    Type
    string
    Description

    The Clerk publishable key from the API Keys page in the Clerk Dashboard.

  • Name
    domain?
    Type
    string
    Description

    The domain of a satellite application in a multi-domain setup.

  • Name
    isSatellite?
    Type
    boolean
    Description

    Whether the instance is a satellite domain in a multi-domain setup. Defaults to false.

  • Name
    proxyUrl?
    Type
    string
    Description

    The proxy URL from a multi-domain setup.

  • Name
    sdkMetadata?
    Type
    { name: string, version: string }
    Description

    Metadata about the SDK.

  • Name
    telemetry?
    Type
    { disabled: boolean, debug: boolean }
    Description

    Telemetry configuration.

  • Name
    userAgent?
    Type
    string
    Description

    The User-Agent request header passed to the Clerk API.

  • Name
    apiUrl?
    Type
    string
    Description

    The Clerk Backend API endpoint. Defaults to 'https://api.clerk.com'.

  • Name
    apiVersion?
    Type
    string
    Description

    The version passed to the Clerk API. Defaults to 'v1'.

  • Name
    audience?
    Type
    string | string[]
    Description

    A string or list of audiences.

Get the userId and other properties

To access the properties of the authenticated user, such as their userId or sessionId, see the following examples:

The following example uses the Next.js auth() helper to access the userId.

import { auth, clerkClient } from '@clerk/nextjs/server'

export async function GET() {
  const { userId } = await auth()

  if (!userId) {
    return Response.json({ error: 'Unauthorized' }, { status: 401 })
  }

  const client = await clerkClient()

  const user = await client.users.getUser(userId)

  return Response.json({ user })
}

The following example uses req.auth to access the userId.

For some backend SDKs, such as Fastify, you will need to use getAuth() instead of req.auth.

const { userId } = req.auth

const response = await clerkClient.users.getUser(userId)

console.log(response)

Feedback

What did you think of this content?
Edit this page on GitHub

Last updated on