@clerk/backend

What is @clerk/backend?

@clerk/backend is a Node.js package that provides backend functionality for authentication and user management. It allows developers to integrate user authentication, manage user sessions, and handle user data securely and efficiently.

What are @clerk/backend's main functionalities?

User Authentication

This feature allows you to authenticate users using a token. The code sample demonstrates how to verify a user's token and retrieve user information.

const { Clerk } = require('@clerk/backend');
const clerk = new Clerk({ apiKey: 'your-api-key' });

async function authenticateUser(token) {
  const user = await clerk.users.verifyToken(token);
  return user;
}

authenticateUser('user-token').then(user => console.log(user)).catch(err => console.error(err));

Session Management

This feature allows you to manage user sessions. The code sample demonstrates how to retrieve a session by its ID.

const { Clerk } = require('@clerk/backend');
const clerk = new Clerk({ apiKey: 'your-api-key' });

async function getSession(sessionId) {
  const session = await clerk.sessions.getSession(sessionId);
  return session;
}

getSession('session-id').then(session => console.log(session)).catch(err => console.error(err));

User Management

This feature allows you to manage user data. The code sample demonstrates how to retrieve user information by user ID.

const { Clerk } = require('@clerk/backend');
const clerk = new Clerk({ apiKey: 'your-api-key' });

async function getUser(userId) {
  const user = await clerk.users.getUser(userId);
  return user;
}

getUser('user-id').then(user => console.log(user)).catch(err => console.error(err));

Other packages similar to @clerk/backend

auth0

Auth0 is a flexible, drop-in solution to add authentication and authorization services to your applications. It provides a wide range of features including social login, multi-factor authentication, and user management. Compared to @clerk/backend, Auth0 offers more extensive integrations and a broader set of features but can be more complex to set up.

firebase-admin

Firebase Admin SDK allows you to integrate Firebase services into your server-side applications. It provides functionalities for user authentication, database management, and cloud messaging. Compared to @clerk/backend, Firebase Admin SDK offers a more comprehensive suite of backend services but may require more configuration and setup.

passport

Passport is an authentication middleware for Node.js that supports a wide range of authentication strategies. It is highly modular and can be integrated with various authentication providers. Compared to @clerk/backend, Passport is more flexible and customizable but requires more effort to implement and manage different authentication strategies.

README

@clerk/backend

Changelog · Report a Bug · Request a Feature · Ask a Question

---

Overview

This package provides Clerk Backend API resources and low-level authentication utilities for JavaScript environments. It is mostly used as the base for other Clerk SDKs but it can be also used on its own.

Features

• Built for V8 isolates (Cloudflare Workers, Vercel Edge Runtime, etc...).
• Make it isomorphic to work across all modern JS runtimes.
• Use options injection for all keys and settings.
• Support multiple CLERK_API_KEY for multiple instance REST access.
• Align JWT key resolution algorithm across all environments (Function param > Environment variable > JWKS from API).
• Tested automatically across different runtimes (Node, CF Workers, Vercel Edge middleware.)
• Clean up Clerk interstitial logic.
• Refactor the Rest Client API to return {data, errors} instead of throwing errors.
• Export a generic verifyToken for Clerk JWTs verification.
• Align AuthData interface for SSR.
• Export CJS and ESM.

How to use

Works on Node >= 16 or on any V8 Isolates runtimes such as Cloudflare Workers.

npm install @clerk/backend

import { Clerk } from '@clerk/backend';

const clerk = Clerk({ apiKey: '...' });

await clerk.users.getUser("user_...");

API

Clerk(options: ClerkOptions)

Create Clerk SDK that includes an HTTP Rest client for the Backend API and session verification helpers. The clerk object contains the following APIs and methods:

import { Clerk } from '@clerk/backend';

const clerk = Clerk({ apiKey: '...' });

await clerk.users.getUser('user_...');

// Available APIs
clerk.allowlistIdentifiers;
clerk.clients;
clerk.emailAddresses;
clerk.emails;
clerk.interstitial;
clerk.invitations;
clerk.organizations;
clerk.phoneNumbers;
clerk.redirectUrls;
clerk.sessions;
clerk.signInTokens;
clerk.smsMessages;
clerk.users;

// These functions should be used by framework-specific libraries, such as @clerk/nextjs or @clerk/remix.

// Compute the authentication state given the request parameters.
clerk.authenticateRequest(options);

// Build debug payload of the request state.
clerk.debugRequestState(requestState);

// Load clerk interstitial from this package
clerk.localInterstitial(options);

// Load clerk interstitial from the public Backend API endpoint
clerk.remotePublicInterstitial(options);

// Load clerk interstitial from the public Private API endpoint (Deprecated)
clerk.remotePrivateInterstitial(options);

verifyToken(token: string, options: VerifyTokenOptions)

Verifies a Clerk generated JWT (i.e. Clerk Session JWT and Clerk JWT templates). The key resolution via JWKS or local values is handled automatically.

import { verifyToken } from '@clerk/backend';

verifyToken(token, {
  issuer: '...',
  authorizedParties: '...',
});

verifyJwt(token: string, options: VerifyJwtOptions)

Verifies a Clerk generated JWT (i.e. Clerk Session JWT and Clerk JWT templates). The key needs to be provided in the options.

import { verifyJwt } from '@clerk/backend';

verifyJwt(token, {
  key: JsonWebKey,
  issuer: '...',
  authorizedParties: '...',
});

decodeJwt(token: string)

Decodes a JWT.

import { decodeJwt } from '@clerk/backend';

decodeJwt(token);

hasValidSignature(jwt: Jwt, jwk: JsonWebKey)

Verifies that the JWT has a valid signature. The key needs to be provided.

import { hasValidSignature } from '@clerk/backend';

hasValidSignature(token, jwk);

debugRequestState(requestState)

Generates a debug payload for the request state

import { debugRequestState } from '@clerk/backend';

debugRequestState(requestState);

loadInterstitialFromLocal(options)

Generates a debug payload for the request state. The debug payload is available via window.__clerk_debug.

import { loadInterstitialFromLocal } from '@clerk/backend';

loadInterstitialFromLocal({
  frontendApi: '...',
  pkgVersion: '...',
  debugData: {},
});

signedInAuthObject(sessionClaims, options)

Builds the AuthObject when the user is signed in.

import { signedInAuthObject } from '@clerk/backend';

signedInAuthObject(jwtPayload, options);

signedOutAuthObject()

Builds the empty AuthObject when the user is signed out.

import { signedOutAuthObject } from '@clerk/backend';

signedOutAuthObject();

sanitizeAuthObject(authObject)

Removes sensitive private metadata from user and organization resources in the AuthObject

import { sanitizeAuthObject } from '@clerk/backend';

sanitizeAuthObject(authObject);

prunePrivateMetadata(obj)

Removes any private_metadata and privateMetadata attributes from the object to avoid leaking sensitive information to the browser during SSR.

import { prunePrivateMetadata } from '@clerk/backend';

prunePrivateMetadata(obj);

License

This project is licensed under the MIT license.

See LICENSE for more information.