clerk · wobsoriano · Aug 7, 2025 · Aug 5, 2025 · Aug 5, 2025 · Aug 6, 2025
diff --git a/.changeset/pink-countries-hunt.md b/.changeset/pink-countries-hunt.md
@@ -0,0 +1,18 @@
+---
+"@clerk/astro": patch
+"@clerk/express": patch
+"@clerk/fastify": patch
+"@clerk/nextjs": patch
+"@clerk/nuxt": patch
+"@clerk/react-router": patch
+"@clerk/remix": patch
+"@clerk/tanstack-react-start": patch
+---
+
+Add ability to define a machine secret key to Clerk BAPI client function
+
+```ts
+const clerkClient = createClerkClient({ machineSecretKey: 'ak_xxxxx' })
+
+clerkClient.machineTokens.create({...})
+```
diff --git a/packages/astro/src/env.d.ts b/packages/astro/src/env.d.ts
@@ -11,6 +11,7 @@ interface InternalEnv {
   readonly CLERK_API_VERSION?: string;
   readonly CLERK_JWT_KEY?: string;
   readonly CLERK_SECRET_KEY?: string;
+  readonly CLERK_MACHINE_SECRET_KEY?: string;
   readonly PUBLIC_CLERK_DOMAIN?: string;
   readonly PUBLIC_CLERK_IS_SATELLITE?: string;
   readonly PUBLIC_CLERK_PROXY_URL?: string;

diff --git a/packages/astro/src/integration/create-integration.ts b/packages/astro/src/integration/create-integration.ts
@@ -190,6 +190,7 @@ function createClerkEnvSchema() {
     PUBLIC_CLERK_TELEMETRY_DISABLED: envField.boolean({ context: 'client', access: 'public', optional: true }),
     PUBLIC_CLERK_TELEMETRY_DEBUG: envField.boolean({ context: 'client', access: 'public', optional: true }),
     CLERK_SECRET_KEY: envField.string({ context: 'server', access: 'secret' }),
+    CLERK_MACHINE_SECRET_KEY: envField.string({ context: 'server', access: 'secret', optional: true }),
     CLERK_JWT_KEY: envField.string({ context: 'server', access: 'secret', optional: true }),
   };
 }

diff --git a/packages/astro/src/server/clerk-client.ts b/packages/astro/src/server/clerk-client.ts
@@ -8,6 +8,7 @@ type CreateClerkClientWithOptions = (context: APIContext, options?: ClerkOptions
 const createClerkClientWithOptions: CreateClerkClientWithOptions = (context, options) =>
   createClerkClient({
     secretKey: getSafeEnv(context).sk,
+    machineSecretKey: getSafeEnv(context).machineSecretKey,
     publishableKey: getSafeEnv(context).pk,
     apiUrl: getSafeEnv(context).apiUrl,
     apiVersion: getSafeEnv(context).apiVersion,

diff --git a/packages/astro/src/server/get-safe-env.ts b/packages/astro/src/server/get-safe-env.ts
@@ -27,6 +27,7 @@ function getSafeEnv(context: ContextOrLocals) {
     proxyUrl: getContextEnvVar('PUBLIC_CLERK_PROXY_URL', context),
     pk: getContextEnvVar('PUBLIC_CLERK_PUBLISHABLE_KEY', context),
     sk: getContextEnvVar('CLERK_SECRET_KEY', context),
+    machineSecretKey: getContextEnvVar('CLERK_MACHINE_SECRET_KEY', context),
     signInUrl: getContextEnvVar('PUBLIC_CLERK_SIGN_IN_URL', context),
     signUpUrl: getContextEnvVar('PUBLIC_CLERK_SIGN_UP_URL', context),
     clerkJsUrl: getContextEnvVar('PUBLIC_CLERK_JS_URL', context),

diff --git a/packages/express/src/utils.ts b/packages/express/src/utils.ts
@@ -18,6 +18,7 @@ export const loadClientEnv = () => {
 export const loadApiEnv = () => {
   return {
     secretKey: process.env.CLERK_SECRET_KEY || '',
+    machineSecretKey: process.env.CLERK_MACHINE_SECRET_KEY || '',
     apiUrl: process.env.CLERK_API_URL || 'https://api.clerk.com',
     apiVersion: process.env.CLERK_API_VERSION || 'v1',
     domain: process.env.CLERK_DOMAIN || '',

diff --git a/packages/fastify/src/clerkClient.ts b/packages/fastify/src/clerkClient.ts
@@ -1,9 +1,10 @@
 import { createClerkClient } from '@clerk/backend';
 
-import { API_URL, API_VERSION, JWT_KEY, SDK_METADATA, SECRET_KEY } from './constants';
+import { API_URL, API_VERSION, JWT_KEY, MACHINE_SECRET_KEY, SDK_METADATA, SECRET_KEY } from './constants';
 
 export const clerkClient = createClerkClient({
   secretKey: SECRET_KEY,
+  machineSecretKey: MACHINE_SECRET_KEY,
   apiUrl: API_URL,
   apiVersion: API_VERSION,
   jwtKey: JWT_KEY,

diff --git a/packages/fastify/src/constants.ts b/packages/fastify/src/constants.ts
@@ -3,6 +3,7 @@ import { apiUrlFromPublishableKey } from '@clerk/shared/apiUrlFromPublishableKey
 
 export const API_VERSION = process.env.CLERK_API_VERSION || 'v1';
 export const SECRET_KEY = process.env.CLERK_SECRET_KEY || '';
+export const MACHINE_SECRET_KEY = process.env.CLERK_MACHINE_SECRET_KEY || '';
 export const PUBLISHABLE_KEY = process.env.CLERK_PUBLISHABLE_KEY || '';
 export const API_URL = process.env.CLERK_API_URL || apiUrlFromPublishableKey(PUBLISHABLE_KEY);
 export const JWT_KEY = process.env.CLERK_JWT_KEY || '';

diff --git a/packages/nextjs/src/server/constants.ts b/packages/nextjs/src/server/constants.ts
@@ -5,6 +5,7 @@ export const CLERK_JS_VERSION = process.env.NEXT_PUBLIC_CLERK_JS_VERSION || '';
 export const CLERK_JS_URL = process.env.NEXT_PUBLIC_CLERK_JS_URL || '';
 export const API_VERSION = process.env.CLERK_API_VERSION || 'v1';
 export const SECRET_KEY = process.env.CLERK_SECRET_KEY || '';
+export const MACHINE_SECRET_KEY = process.env.CLERK_MACHINE_SECRET_KEY || '';
 export const PUBLISHABLE_KEY = process.env.NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY || '';
 export const ENCRYPTION_KEY = process.env.CLERK_ENCRYPTION_KEY || '';
 export const API_URL = process.env.CLERK_API_URL || apiUrlFromPublishableKey(PUBLISHABLE_KEY);

diff --git a/packages/nextjs/src/server/createClerkClient.ts b/packages/nextjs/src/server/createClerkClient.ts
@@ -5,6 +5,7 @@ import {
   API_VERSION,
   DOMAIN,
   IS_SATELLITE,
+  MACHINE_SECRET_KEY,
   PROXY_URL,
   PUBLISHABLE_KEY,
   SDK_METADATA,
@@ -22,6 +23,7 @@ const clerkClientDefaultOptions = {
   proxyUrl: PROXY_URL,
   domain: DOMAIN,
   isSatellite: IS_SATELLITE,
+  machineSecretKey: MACHINE_SECRET_KEY,
   sdkMetadata: SDK_METADATA,
   telemetry: {
     disabled: TELEMETRY_DISABLED,

diff --git a/packages/nuxt/src/global.d.ts b/packages/nuxt/src/global.d.ts
@@ -10,6 +10,7 @@ declare module 'nuxt/schema' {
   interface RuntimeConfig {
     clerk: {
       secretKey?: string;
+      machineSecretKey?: string;
       jwtKey?: string;
       webhookSigningSecret?: string;
     };

diff --git a/packages/nuxt/src/module.ts b/packages/nuxt/src/module.ts
@@ -78,6 +78,7 @@ export default defineNuxtModule<ModuleOptions>({
       // Private keys available only on within server-side
       clerk: {
         secretKey: undefined,
+        machineSecretKey: undefined,
         jwtKey: undefined,
         webhookSigningSecret: undefined,
       },

diff --git a/packages/nuxt/src/runtime/server/clerkClient.ts b/packages/nuxt/src/runtime/server/clerkClient.ts
@@ -16,6 +16,7 @@ export function clerkClient(event: H3Event) {
     domain: runtimeConfig.public.clerk.domain,
     isSatellite: runtimeConfig.public.clerk.isSatellite,
     secretKey: runtimeConfig.clerk.secretKey,
+    machineSecretKey: runtimeConfig.clerk.machineSecretKey,
     jwtKey: runtimeConfig.clerk.jwtKey,
     telemetry: {
       disabled: isTruthy(runtimeConfig.public.clerk.telemetry?.disabled),

diff --git a/packages/react-router/src/ssr/authenticateRequest.ts b/packages/react-router/src/ssr/authenticateRequest.ts
@@ -13,7 +13,7 @@ export async function authenticateRequest(
   const { request } = args;
   const { audience, authorizedParties } = opts;
 
-  const { apiUrl, secretKey, jwtKey, proxyUrl, isSatellite, domain, publishableKey } = opts;
+  const { apiUrl, secretKey, jwtKey, proxyUrl, isSatellite, domain, publishableKey, machineSecretKey } = opts;
   const { signInUrl, signUpUrl, afterSignInUrl, afterSignUpUrl } = opts;
 
   const requestState = await createClerkClient({
@@ -24,6 +24,7 @@ export async function authenticateRequest(
     isSatellite,
     domain,
     publishableKey,
+    machineSecretKey,
     userAgent: `${PACKAGE_NAME}@${PACKAGE_VERSION}`,
   }).authenticateRequest(patchRequest(request), {
     audience,

diff --git a/packages/react-router/src/ssr/loadOptions.ts b/packages/react-router/src/ssr/loadOptions.ts
@@ -22,6 +22,7 @@ export const loadOptions = (args: LoaderFunctionArgs, overrides: RootAuthLoaderO
   // 4. Then try from globalThis (Cloudflare Workers).
   // 5. Then from loader context (Cloudflare Pages).
   const secretKey = overrides.secretKey || getEnvVariable('CLERK_SECRET_KEY', context);
+  const machineSecretKey = overrides.machineSecretKey || getEnvVariable('CLERK_MACHINE_SECRET_KEY', context);
   const publishableKey = overrides.publishableKey || getPublicEnvVariables(context).publishableKey;
   const jwtKey = overrides.jwtKey || getEnvVariable('CLERK_JWT_KEY', context);
   const apiUrl = getEnvVariable('CLERK_API_URL', context) || apiUrlFromPublishableKey(publishableKey);
@@ -67,6 +68,7 @@ export const loadOptions = (args: LoaderFunctionArgs, overrides: RootAuthLoaderO
     // used to append options that are not initialized from env
     ...overrides,
     secretKey,
+    machineSecretKey,
     publishableKey,
     jwtKey,
     apiUrl,

diff --git a/packages/react-router/src/ssr/types.ts b/packages/react-router/src/ssr/types.ts
@@ -25,6 +25,10 @@ export type RootAuthLoaderOptions = {
    * Used to override the CLERK_SECRET_KEY env variable if needed.
    */
   secretKey?: string;
+  /**
+   * Used to override the CLERK_MACHINE_SECRET_KEY env variable if needed.
+   */
+  machineSecretKey?: string;
   /**
    * @deprecated Use [session token claims](https://clerk.com/docs/backend-requests/making/custom-session-token) instead.
    */

diff --git a/packages/remix/src/ssr/authenticateRequest.ts b/packages/remix/src/ssr/authenticateRequest.ts
@@ -13,7 +13,7 @@ export async function authenticateRequest(
   const { request } = args;
   const { audience, authorizedParties } = opts;
 
-  const { apiUrl, secretKey, jwtKey, proxyUrl, isSatellite, domain, publishableKey } = opts;
+  const { apiUrl, secretKey, jwtKey, proxyUrl, isSatellite, domain, publishableKey, machineSecretKey } = opts;
   const { signInUrl, signUpUrl, afterSignInUrl, afterSignUpUrl } = opts;
 
   const requestState = await createClerkClient({
@@ -32,6 +32,7 @@ export async function authenticateRequest(
     signUpUrl,
     afterSignInUrl,
     afterSignUpUrl,
+    machineSecretKey,
   });
 
   const locationHeader = requestState.headers.get(constants.Headers.Location);

diff --git a/packages/remix/src/ssr/loadOptions.ts b/packages/remix/src/ssr/loadOptions.ts
@@ -20,6 +20,7 @@ export const loadOptions = (args: LoaderFunctionArgs, overrides: RootAuthLoaderO
   // 3. Then try from globalThis (Cloudflare Workers).
   // 4. Then from loader context (Cloudflare Pages).
   const secretKey = overrides.secretKey || getEnvVariable('CLERK_SECRET_KEY', context) || '';
+  const machineSecretKey = overrides.machineSecretKey || getEnvVariable('CLERK_MACHINE_SECRET_KEY', context);
   const publishableKey = overrides.publishableKey || getEnvVariable('CLERK_PUBLISHABLE_KEY', context) || '';
   const jwtKey = overrides.jwtKey || getEnvVariable('CLERK_JWT_KEY', context);
   const apiUrl = getEnvVariable('CLERK_API_URL', context) || apiUrlFromPublishableKey(publishableKey);
@@ -69,6 +70,7 @@ export const loadOptions = (args: LoaderFunctionArgs, overrides: RootAuthLoaderO
     // used to append options that are not initialized from env
     ...overrides,
     secretKey,
+    machineSecretKey,
     publishableKey,
     jwtKey,
     apiUrl,

diff --git a/packages/remix/src/ssr/types.ts b/packages/remix/src/ssr/types.ts
@@ -17,6 +17,10 @@ export type RootAuthLoaderOptions = {
   publishableKey?: string;
   jwtKey?: string;
   secretKey?: string;
+  /**
+   * Used to override the CLERK_MACHINE_SECRET_KEY env variable if needed.
+   */
+  machineSecretKey?: string;
   /**
    * @deprecated Use [session token claims](https://clerk.com/docs/backend-requests/making/custom-session-token) instead.
    */

diff --git a/packages/tanstack-react-start/src/server/authenticateRequest.ts b/packages/tanstack-react-start/src/server/authenticateRequest.ts
@@ -13,12 +13,14 @@ export async function authenticateRequest(
 ): Promise<AuthenticatedState | UnauthenticatedState> {
   const { audience, authorizedParties } = opts;
 
-  const { apiUrl, secretKey, jwtKey, proxyUrl, isSatellite, domain, publishableKey, acceptsToken } = opts;
+  const { apiUrl, secretKey, jwtKey, proxyUrl, isSatellite, domain, publishableKey, acceptsToken, machineSecretKey } =
+    opts;
   const { signInUrl, signUpUrl, afterSignInUrl, afterSignUpUrl } = opts;
 
   const requestState = await createClerkClient({
     apiUrl,
     secretKey,
+    machineSecretKey,
     jwtKey,
     proxyUrl,
     isSatellite,

diff --git a/packages/tanstack-react-start/src/server/clerkClient.ts b/packages/tanstack-react-start/src/server/clerkClient.ts
@@ -7,6 +7,7 @@ const clerkClient = (options?: ClerkOptions): ClerkClient => {
   const commonEnv = commonEnvs();
   return createClerkClient({
     secretKey: commonEnv.SECRET_KEY,
+    machineSecretKey: commonEnv.MACHINE_SECRET_KEY,
     publishableKey: commonEnv.PUBLISHABLE_KEY,
     apiUrl: commonEnv.API_URL,
     apiVersion: commonEnv.API_VERSION,

diff --git a/packages/tanstack-react-start/src/server/constants.ts b/packages/tanstack-react-start/src/server/constants.ts
@@ -22,6 +22,7 @@ export const commonEnvs = () => {
     // Server-only environment variables
     API_VERSION: getEnvVariable('CLERK_API_VERSION') || 'v1',
     SECRET_KEY: getEnvVariable('CLERK_SECRET_KEY'),
+    MACHINE_SECRET_KEY: getEnvVariable('CLERK_MACHINE_SECRET_KEY'),
     ENCRYPTION_KEY: getEnvVariable('CLERK_ENCRYPTION_KEY'),
     CLERK_JWT_KEY: getEnvVariable('CLERK_JWT_KEY'),
     API_URL: getEnvVariable('CLERK_API_URL') || apiUrlFromPublishableKey(publicEnvs.publishableKey),

diff --git a/packages/tanstack-react-start/src/server/loadOptions.ts b/packages/tanstack-react-start/src/server/loadOptions.ts
@@ -15,6 +15,7 @@ export const loadOptions = (request: Request, overrides: LoaderOptions = {}) =>
   const clerkRequest = createClerkRequest(patchRequest(request));
   const commonEnv = commonEnvs();
   const secretKey = overrides.secretKey || commonEnv.SECRET_KEY;
+  const machineSecretKey = overrides.machineSecretKey || commonEnv.MACHINE_SECRET_KEY;
   const publishableKey = overrides.publishableKey || commonEnv.PUBLISHABLE_KEY;
   const jwtKey = overrides.jwtKey || commonEnv.CLERK_JWT_KEY;
   const apiUrl = getEnvVariable('CLERK_API_URL') || apiUrlFromPublishableKey(publishableKey);
@@ -52,6 +53,7 @@ export const loadOptions = (request: Request, overrides: LoaderOptions = {}) =>
     // used to append options that are not initialized from env
     ...overrides,
     secretKey,
+    machineSecretKey,
     publishableKey,
     jwtKey,
     apiUrl,

diff --git a/packages/tanstack-react-start/src/server/types.ts b/packages/tanstack-react-start/src/server/types.ts
@@ -12,6 +12,7 @@ export type LoaderOptions = {
   publishableKey?: string;
   jwtKey?: string;
   secretKey?: string;
+  machineSecretKey?: string;
   signInUrl?: string;
   signUpUrl?: string;
 } & Pick<VerifyTokenOptions, 'audience' | 'authorizedParties'> &