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

wobsoriano · 2025-08-06T14:25:57Z

Description

This PR adds the ability to create, revoke, and verify machine-to-machine tokens using the BAPI client. All M2M token endpoints can be authorized with a machine secret key:

const clerkClient = createClerkClient({
    machineSecretKey: process.env.CLERK_MACHINE_SECRET_KEY
})

// All of the methods below will use the machine secret key from clerkClient
clerkClient.m2mTokens.create({...})
clerkClient.m2mTokens.revoke({...})
clerkClient.m2mTokens.verifySecret({...})

// You can also use a machine secret key per method
clerkClient.m2mTokens.create({ machineSecretKey: 'ak_xxx', ...rest })
clerkClient.m2mTokens.revoke({ machineSecretKey: 'ak_xxx', ...rest }))
clerkClient.m2mTokens.verifySecret({ machineSecretKey: 'ak_xxx', ...rest }))

To verify a machine-to-machine token using authenticateRequest():

const clerkClient = createClerkClient({
    machineSecretKey: process.env.CLERK_MACHINE_SECRET_KEY
})

const authReq = await clerkClient.authenticateRequest(c.req.raw, {
  acceptsToken: 'm2m_token',
})

Additionally, this PR introduces 2 breaking changes:

Removes the name property from m2m tokens. This change is part of the breaking changes to M2M endpoints documented here.
machine_token token type is now m2m_token for better terminology. Please see this Slack convo for more info.

Since this feature is still in private beta, a minor version bump should suffice.

A demo video on what's happening in this change.

Unit tests have been added, but E2E tests will be implemented in a separate PR.

Resolves USER-2264

Checklist

pnpm test runs as expected.
pnpm build runs as expected.
(If applicable) JSDoc comments have been added or updated for any package exports
(If applicable) Documentation has been updated

Type of change

Summary by CodeRabbit

New Features
- Introduced endpoints for managing machine-to-machine (M2M) tokens, including creation, revocation, and verification.
- Added support for authenticating requests using a machine secret key and specifying acceptance of M2M tokens.
- Enabled specifying a machine secret key when creating Clerk client instances across multiple frameworks.
Refactor
- Renamed all references from "machine_token" to "m2m_token" for improved clarity and consistency across the platform.
Bug Fixes
- Improved token authentication logic to support both machine secret keys and instance secret keys for M2M tokens.
Tests
- Added and updated comprehensive tests to cover M2M token management and authentication scenarios.
Documentation
- Updated usage examples to reflect new M2M token endpoints and authentication methods.

…ient init (#6478)

coderabbitai

Actionable comments posted: 1

🔭 Outside diff range comments (1)

packages/astro/src/server/get-safe-env.ts (1)

23-41: Add explicit return type for better type safety.

The getSafeEnv function should have an explicit return type annotation to improve type safety and developer experience, especially since it now includes the new machineSecretKey property.

-function getSafeEnv(context: ContextOrLocals) {
+function getSafeEnv(context: ContextOrLocals): {
+  domain: string | undefined;
+  isSatellite: boolean;
+  proxyUrl: string | undefined;
+  pk: string | undefined;
+  sk: string | undefined;
+  machineSecretKey: string | undefined;
+  signInUrl: string | undefined;
+  signUpUrl: string | undefined;
+  clerkJsUrl: string | undefined;
+  clerkJsVariant: 'headless' | '' | undefined;
+  clerkJsVersion: string | undefined;
+  apiVersion: string | undefined;
+  apiUrl: string | undefined;
+  telemetryDisabled: boolean;
+  telemetryDebug: boolean;
+} {

📜 Review details

Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 0297391 and dc2dc84.

📒 Files selected for processing (24)

.changeset/pink-countries-hunt.md (1 hunks)
packages/astro/src/env.d.ts (1 hunks)
packages/astro/src/integration/create-integration.ts (1 hunks)
packages/astro/src/server/clerk-client.ts (1 hunks)
packages/astro/src/server/get-safe-env.ts (1 hunks)
packages/express/src/utils.ts (1 hunks)
packages/fastify/src/clerkClient.ts (1 hunks)
packages/fastify/src/constants.ts (1 hunks)
packages/nextjs/src/server/constants.ts (1 hunks)
packages/nextjs/src/server/createClerkClient.ts (2 hunks)
packages/nuxt/src/global.d.ts (1 hunks)
packages/nuxt/src/module.ts (1 hunks)
packages/nuxt/src/runtime/server/clerkClient.ts (1 hunks)
packages/react-router/src/ssr/authenticateRequest.ts (2 hunks)
packages/react-router/src/ssr/loadOptions.ts (2 hunks)
packages/react-router/src/ssr/types.ts (1 hunks)
packages/remix/src/ssr/authenticateRequest.ts (2 hunks)
packages/remix/src/ssr/loadOptions.ts (2 hunks)
packages/remix/src/ssr/types.ts (1 hunks)
packages/tanstack-react-start/src/server/authenticateRequest.ts (1 hunks)
packages/tanstack-react-start/src/server/clerkClient.ts (1 hunks)
packages/tanstack-react-start/src/server/constants.ts (1 hunks)
packages/tanstack-react-start/src/server/loadOptions.ts (2 hunks)
packages/tanstack-react-start/src/server/types.ts (1 hunks)

✅ Files skipped from review due to trivial changes (13)

packages/astro/src/env.d.ts
packages/nuxt/src/global.d.ts
packages/react-router/src/ssr/types.ts
packages/astro/src/server/clerk-client.ts
packages/tanstack-react-start/src/server/clerkClient.ts
packages/tanstack-react-start/src/server/types.ts
packages/nextjs/src/server/constants.ts
packages/remix/src/ssr/types.ts
packages/tanstack-react-start/src/server/constants.ts
packages/astro/src/integration/create-integration.ts
packages/fastify/src/constants.ts
packages/remix/src/ssr/loadOptions.ts
.changeset/pink-countries-hunt.md

🧰 Additional context used

📓 Path-based instructions (7)

**/*.{js,jsx,ts,tsx}