@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);

Support

You can get in touch with us in any of the following ways:

• Join our official community Discord server
• Open a GitHub support issue
• Contact options listed on our Support page

Contributing

We're open to all community contributions! If you'd like to contribute in any way, please read our contribution guidelines.

Security

@clerk/backend follows good practices of security, but 100% security cannot be assured.

@clerk/backend is provided "as is" without any warranty. Use at your own risk.

For more information and to report security issues, please refer to our security documentation.

License

This project is licensed under the MIT license.

See LICENSE for more information.