feat(backend): Introduce M2M endpoints authentication using machine secret keys (#6479)

Author: wobsoriano

.changeset/hot-tables-worry.md

@@ -0,0 +1,83 @@
+---
+"@clerk/backend": minor
+---
+
+Adds machine-to-machine endpoints to the Backend SDK:
+
+**Note:** Renamed from "machine_tokens" to "m2m_tokens" for clarity and consistency with canonical terminology. This avoids confusion with other machine-related concepts like machine secrets.
+
+### Create M2M Tokens
+
+A machine secret is required when creating M2M tokens.
+
+```ts
+const clerkClient = createClerkClient({
+    machineSecretKey: process.env.CLERK_MACHINE_SECRET_KEY
+})
+
+clerkClient.m2mTokens.create({
+    // or pass as an option here
+    // machineSecretKey: process.env.CLERK_MACHINE_SECRET_KEY
+    secondsUntilExpiration: 3600,
+})
+```
+
+### Revoke M2M Tokens
+
+You can revoke tokens using either a machine secret or instance secret:
+
+```ts
+// Using machine secret
+const clerkClient = createClerkClient({ machineSecretKey: process.env.CLERK_MACHINE_SECRET_KEY })
+clerkClient.m2mTokens.revoke({
+    // or pass as an option here
+    // machineSecretKey: process.env.CLERK_MACHINE_SECRET_KEY
+    m2mTokenId: 'mt_xxxxx',
+    revocationReason: 'Revoked by user',
+})
+
+// Using instance secret (default)
+const clerkClient = createClerkClient({ secretKey: 'sk_xxxx' })
+clerkClient.m2mTokens.revoke({
+    m2mTokenId: 'mt_xxxxx',
+    revocationReason: 'Revoked by user',
+})
+```
+
+### Verify M2M Tokens
+
+You can verify tokens using either a machine secret or instance secret:
+
+```ts
+// Using machine secret
+const clerkClient = createClerkClient({ machineSecretKey: process.env.CLERK_MACHINE_SECRET_KEY })
+clerkClient.m2mTokens.verifySecret({
+    // or pass as an option here
+    // machineSecretKey: process.env.CLERK_MACHINE_SECRET_KEY
+    secret: 'mt_secret_xxxxx',
+})
+
+// Using instance secret (default)
+const clerkClient = createClerkClient({ secretKey: 'sk_xxxx' })
+clerkClient.m2mTokens.verifySecret({
+    secret: 'mt_secret_xxxxx',
+})
+```
+
+To verify machine-to-machine tokens using when using `authenticateRequest()` with a machine secret, use the `machineSecret` option:
+
+```ts
+const clerkClient = createClerkClient({
+    machineSecretKey: process.env.CLERK_MACHINE_SECRET_KEY
+})
+
+const authReq = await clerkClient.authenticateRequest(c.req.raw, {
+  // or pass as an option here
+  // machineSecretKey: process.env.CLERK_MACHINE_SECRET_KEY
+  acceptsToken: 'm2m_token', // previously machine_token
+})
+
+if (authReq.isAuthenticated) {
+    // ... do something
+}
+```

.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.m2mTokens.create({...})
+```

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;

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

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,

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