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

License

This project is licensed under the MIT license.

See LICENSE for more information.