@clerk/backend

@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_SECRET_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.)
• 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.js >=18.17.0 (or later) or on any V8 Isolates runtimes (eg Cloudflare Workers).

npm install @clerk/backend

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

const clerk = createClerkClient({ secretKey: '...' });

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

API

createClerkClient(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 { createClerkClient } from '@clerk/backend';

const clerk = createClerkClient({ secretKey: '...' });

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

// Available APIs
clerk.allowlistIdentifiers;
clerk.clients;
clerk.emailAddresses;
clerk.emails;
clerk.invitations;
clerk.organizations;
clerk.phoneNumbers;
clerk.redirectUrls;
clerk.sessions;
clerk.signInTokens;
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);

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';

const { result, error } = await 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/jwt';

const { result, error } = verifyJwt(token, {
  key: JsonWebKey | string,
  authorizedParties: '...',
});

decodeJwt(token: string)

Decodes a JWT.

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

const { result, error } = decodeJwt(token);

hasValidSignature(jwt: Jwt, key: JsonWebKey | string)

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

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

const { result, error } = await hasValidSignature(token, jwk);

debugRequestState(requestState)

Generates a debug payload for the request state

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

debugRequestState(requestState);

signedInAuthObject(sessionClaims, options)

Builds the AuthObject when the user is signed in.

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

signedInAuthObject(jwtPayload, options);

signedOutAuthObject()

Builds the empty AuthObject when the user is signed out.

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

signedOutAuthObject();

sanitizeAuthObject(authObject)

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

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

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/internal';

prunePrivateMetadata(obj);

Support

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

• Join our official community Discord server
• Create a GitHub Discussion
• 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.

Similar packages

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.