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_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.