feat(backend,nextjs): Introduce machine authentication

.changeset/bumpy-carpets-study.md

@@ -0,0 +1,40 @@
+---
+'@clerk/backend': major
+---
+
+Introduces machine authentication, supporting four token types: `api_key`, `oauth_token`, `machine_token`, and `session_token`. For backwards compatibility, `session_token` remains the default when no token type is specified. This enables machine-to-machine authentication and use cases such as API keys and OAuth integrations. Existing applications continue to work without modification.
+
+You can specify which token types are allowed by using the `acceptsToken` option in the `authenticateRequest()` function. This option can be set to a specific type, an array of types, or `'any'` to accept all supported tokens.
+
+Example usage:
+
+```ts
+import express from 'express';
+import { clerkClient } from '@clerk/backend';
+
+const app = express();
+
+app.use(async (req, res, next) => {
+ const requestState = await clerkClient.authenticateRequest(req, {
+ acceptsToken: 'any'
+ });
+
+ if (!requestState.isAuthenticated) {
+ // do something for unauthenticated requests
+ }
+
+ const authObject = requestState.toAuth();
+
+ if (authObject.tokenType === 'session_token') {
+ console.log('this is session token from a user')
+ } else {
+ console.log('this is some other type of machine token')
+ console.log('more specifically, a ' + authObject.tokenType)
+ }
+
+ // Attach the auth object to locals so downstream handlers
+ // and middleware can access it
+ res.locals.auth = authObject;
+ next();
+});
+```

.changeset/chatty-lions-stay.md

@@ -0,0 +1,30 @@
+---
+'@clerk/tanstack-react-start': minor
+'@clerk/agent-toolkit': minor
+'@clerk/react-router': minor
+'@clerk/express': minor
+'@clerk/fastify': minor
+'@clerk/astro': minor
+'@clerk/remix': minor
+'@clerk/nuxt': minor
+---
+
+Machine authentication is now supported for advanced use cases via the backend SDK. You can use `clerkClient.authenticateRequest` to validate machine tokens (such as API keys, OAuth tokens, and machine-to-machine tokens). No new helpers are included in these packages yet.
+
+Example (Astro):
+
+```ts
+import { clerkClient } from '@clerk/astro/server';
+
+export const GET: APIRoute = ({ request }) => {
+ const requestState = await clerkClient.authenticateRequest(request, {
+ acceptsToken: 'api_key'
+ });
+
+ if (!requestState.isAuthenticated) {
+ return new Response(401, { message: 'Unauthorized' })
+ }
+
+ return new Response(JSON.stringify(requestState.toAuth()))
+}
+```

.changeset/fast-turkeys-melt.md

@@ -0,0 +1,57 @@
+---
+'@clerk/nextjs': minor
+---
+
+Introduces machine authentication, supporting four token types: `api_key`, `oauth_token`, `machine_token`, and `session_token`. For backwards compatibility, `session_token` remains the default when no token type is specified. This enables machine-to-machine authentication and use cases such as API keys and OAuth integrations. Existing applications continue to work without modification.
+
+You can specify which token types are allowed for a given route or handler using the `acceptsToken` property in the `auth()` helper, or the `token` property in the `auth.protect()` helper. Each can be set to a specific type, an array of types, or `'any'` to accept all supported tokens.
+
+Example usage in Nextjs middleware:
+
+```ts
+import { clerkMiddleware, createRouteMatcher } from '@clerk/nextjs/server';
+
+const isOAuthAccessible = createRouteMatcher(['/oauth(.*)'])
+const isApiKeyAccessible = createRouteMatcher(['/api(.*)'])
+const isMachineTokenAccessible = createRouteMatcher(['/m2m(.*)'])
+const isUserAccessible = createRouteMatcher(['/user(.*)'])
+const isAccessibleToAnyValidToken = createRouteMatcher(['/any(.*)'])
+
+export default clerkMiddleware(async (auth, req) => {
+ if (isOAuthAccessible(req)) await auth.protect({ token: 'oauth_token' })
+ if (isApiKeyAccessible(req)) await auth.protect({ token: 'api_key' })
+ if (isMachineTokenAccessible(req)) await auth.protect({ token: 'machine_token' })
+ if (isUserAccessible(req)) await auth.protect({ token: 'session_token' })
+
+ if (isAccessibleToAnyValidToken(req)) await auth.protect({ token: 'any' })
+});
+
+export const config = {
+ matcher: [
+ '/((?!_next|[^?]*\\.(?:html?|css|js(?!on)|jpe?g|webp|png|gif|svg|ttf|woff2?|ico|csv|docx?|xlsx?|zip|webmanifest)).*)',
+ '/(api|trpc)(.*)',
+ ],
+}
+```
+
+Leaf node route protection:
+
+```ts
+import { auth } from '@clerk/nextjs/server'
+
+// In this example, we allow users and oauth tokens with the "profile" scope
+// to access the data. Other types of tokens are rejected.
+function POST(req, res) {
+ const authObject = await auth({ acceptsToken: ['session_token', 'oauth_token'] })
+
+ if (authObject.tokenType === 'oauth_token' &&
+ !authObject.scopes?.includes('profile')) {
+ throw new Error('Unauthorized: OAuth token missing the "profile" scope')
+ }
+
+ // get data from db using userId
+ const data = db.select().from(user).where(eq(user.id, authObject.userId))
+
+ return { data }
+}
+```

.typedoc/__tests__/__snapshots__/file-structure.test.ts.snap

@@ -118,6 +118,7 @@ exports[`Typedoc output > should have a deliberate file structure 1`] = `
  "shared/version-selector.mdx",
  "nextjs/auth.mdx",
  "nextjs/build-clerk-props.mdx",
+ "nextjs/clerk-middleware-auth-object.mdx",
  "nextjs/clerk-middleware-options.mdx",
  "nextjs/clerk-middleware.mdx",
  "nextjs/create-async-get-auth.mdx",
@@ -139,6 +140,7 @@ exports[`Typedoc output > should have a deliberate file structure 1`] = `
  "clerk-react/use-sign-in.mdx",
  "clerk-react/use-sign-up.mdx",
  "clerk-react/use-user.mdx",
+ "backend/verify-machine-auth-token.mdx",
  "backend/verify-token-options.mdx",
  "backend/verify-token.mdx",
  "backend/verify-webhook-options.mdx",

packages/agent-toolkit/src/lib/types.ts

@@ -1,4 +1,5 @@
-import type { AuthObject, ClerkClient } from '@clerk/backend';
+import type { ClerkClient } from '@clerk/backend';
+import type { SignedInAuthObject, SignedOutAuthObject } from '@clerk/backend/internal';
 
 import type { ClerkTool } from './clerk-tool';
 
@@ -12,7 +13,7 @@ export type ToolkitParams = {
  * @default {}
  */
  authContext?: Pick<
- AuthObject,
+ SignedInAuthObject | SignedOutAuthObject,
  'userId' | 'sessionId' | 'sessionClaims' | 'orgId' | 'orgRole' | 'orgSlug' | 'orgPermissions' | 'actor'
  >;
  /**

packages/astro/src/server/clerk-middleware.ts

@@ -1,5 +1,12 @@
-import type { AuthObject, ClerkClient } from '@clerk/backend';
-import type { AuthenticateRequestOptions, ClerkRequest, RedirectFun, RequestState } from '@clerk/backend/internal';
+import type { ClerkClient } from '@clerk/backend';
+import type {
+ AuthenticateRequestOptions,
+ ClerkRequest,
+ RedirectFun,
+ RequestState,
+ SignedInAuthObject,
+ SignedOutAuthObject,
+} from '@clerk/backend/internal';
 import { AuthStatus, constants, createClerkRequest, createRedirect } from '@clerk/backend/internal';
 import { isDevelopmentFromSecretKey } from '@clerk/shared/keys';
 import { handleNetlifyCacheInDevInstance } from '@clerk/shared/netlifyCacheHandler';
@@ -28,7 +35,7 @@ const CONTROL_FLOW_ERROR = {
  REDIRECT_TO_SIGN_IN: 'CLERK_PROTECT_REDIRECT_TO_SIGN_IN',
 };
 
-type ClerkMiddlewareAuthObject = AuthObject & {
+type ClerkMiddlewareAuthObject = (SignedInAuthObject | SignedOutAuthObject) & {
  redirectToSignIn: (opts?: { returnBackUrl?: URL | string | null }) => Response;
 };
 

packages/astro/src/server/get-auth.ts

@@ -1,4 +1,4 @@
-import type { AuthObject } from '@clerk/backend';
+import type { SignedInAuthObject, SignedOutAuthObject } from '@clerk/backend/internal';
 import { AuthStatus, signedInAuthObject, signedOutAuthObject } from '@clerk/backend/internal';
 import { decodeJwt } from '@clerk/backend/jwt';
 import type { PendingSessionOptions } from '@clerk/types';
@@ -7,7 +7,7 @@ import type { APIContext } from 'astro';
 import { getSafeEnv } from './get-safe-env';
 import { getAuthKeyFromRequest } from './utils';
 
-export type GetAuthReturn = AuthObject;
+export type GetAuthReturn = SignedInAuthObject | SignedOutAuthObject;
 
 export const createGetAuth = ({ noAuthStatusMessage }: { noAuthStatusMessage: string }) => {
  return (

packages/backend/src/__tests__/exports.test.ts

@@ -22,6 +22,8 @@ describe('subpath /errors exports', () => {
  it('should not include a breaking change', () => {
  expect(Object.keys(errorExports).sort()).toMatchInlineSnapshot(`
  [
+ "MachineTokenVerificationError",
+ "MachineTokenVerificationErrorCode",
  "SignJWTError",
  "TokenVerificationError",
  "TokenVerificationErrorAction",
@@ -37,18 +39,25 @@ describe('subpath /internal exports', () => {
  expect(Object.keys(internalExports).sort()).toMatchInlineSnapshot(`
  [
  "AuthStatus",
+ "TokenType",
+ "authenticatedMachineObject",
  "constants",
  "createAuthenticateRequest",
  "createClerkRequest",
  "createRedirect",
  "debugRequestState",
  "decorateObjectWithResources",
+ "getMachineTokenType",
+ "isMachineToken",
+ "isTokenTypeAccepted",
  "makeAuthObjectSerializable",
  "reverificationError",
  "reverificationErrorResponse",
  "signedInAuthObject",
  "signedOutAuthObject",
  "stripPrivateDataFromObject",
+ "unauthenticatedMachineObject",
+ "verifyMachineAuthToken",
  ]
  `);
  });

packages/backend/src/api/endpoints/APIKeysApi.ts

@@ -0,0 +1,15 @@
+import { joinPaths } from '../../util/path';
+import type { APIKey } from '../resources/APIKey';
+import { AbstractAPI } from './AbstractApi';
+
+const basePath = '/api_keys';
+
+export class APIKeysAPI extends AbstractAPI {
+ async verifySecret(secret: string) {
+ return this.request<APIKey>({
+ method: 'POST',
+ path: joinPaths(basePath, 'verify'),
+ bodyParams: { secret },
+ });
+ }
+}

packages/backend/src/api/endpoints/IdPOAuthAccessTokenApi.ts

@@ -0,0 +1,15 @@
+import { joinPaths } from '../../util/path';
+import type { IdPOAuthAccessToken } from '../resources';
+import { AbstractAPI } from './AbstractApi';
+
+const basePath = '/oauth_applications/access_tokens';
+
+export class IdPOAuthAccessTokenApi extends AbstractAPI {
+ async verifySecret(secret: string) {
+ return this.request<IdPOAuthAccessToken>({
+ method: 'POST',
+ path: joinPaths(basePath, 'verify'),
+ bodyParams: { secret },
+ });
+ }
+}

packages/backend/src/api/endpoints/MachineTokensApi.ts

@@ -0,0 +1,15 @@
+import { joinPaths } from '../../util/path';
+import type { MachineToken } from '../resources/MachineToken';
+import { AbstractAPI } from './AbstractApi';
+
+const basePath = '/m2m_tokens';
+
+export class MachineTokensApi extends AbstractAPI {
+ async verifySecret(secret: string) {
+ return this.request<MachineToken>({
+ method: 'POST',
+ path: joinPaths(basePath, 'verify'),
+ bodyParams: { secret },
+ });
+ }
+}

packages/backend/src/api/endpoints/index.ts

@@ -2,13 +2,16 @@ export * from './ActorTokenApi';
 export * from './AccountlessApplicationsAPI';
 export * from './AbstractApi';
 export * from './AllowlistIdentifierApi';
+export * from './APIKeysApi';
 export * from './BetaFeaturesApi';
 export * from './BlocklistIdentifierApi';
 export * from './ClientApi';
 export * from './DomainApi';
 export * from './EmailAddressApi';
+export * from './IdPOAuthAccessTokenApi';
 export * from './InstanceApi';
 export * from './InvitationApi';
+export * from './MachineTokensApi';
 export * from './JwksApi';
 export * from './JwtTemplatesApi';
 export * from './OrganizationApi';

packages/backend/src/api/factory.ts

@@ -2,15 +2,18 @@ import {
  AccountlessApplicationAPI,
  ActorTokenAPI,
  AllowlistIdentifierAPI,
+ APIKeysAPI,
  BetaFeaturesAPI,
  BlocklistIdentifierAPI,
  ClientAPI,
  DomainAPI,
  EmailAddressAPI,
+ IdPOAuthAccessTokenApi,
  InstanceAPI,
  InvitationAPI,
  JwksAPI,
  JwtTemplatesApi,
+ MachineTokensApi,
  OAuthApplicationsApi,
  OrganizationAPI,
  PhoneNumberAPI,
@@ -47,6 +50,27 @@ export function createBackendApiClient(options: CreateBackendApiOptions) {
  emailAddresses: new EmailAddressAPI(request),
  instance: new InstanceAPI(request),
  invitations: new InvitationAPI(request),
+ // Using "/" instead of an actual version since they're bapi-proxy endpoints.
+ // bapi-proxy connects directly to C1 without URL versioning,
+ // while API versioning is handled through the Clerk-API-Version header.
+ machineTokens: new MachineTokensApi(
+ buildRequest({
+ ...options,
+ apiVersion: '/',
+ }),
+ ),
+ idPOAuthAccessToken: new IdPOAuthAccessTokenApi(
+ buildRequest({
+ ...options,
+ apiVersion: '/',
+ }),
+ ),
+ apiKeys: new APIKeysAPI(
+ buildRequest({
+ ...options,
+ apiVersion: '/',
+ }),
+ ),
  jwks: new JwksAPI(request),
  jwtTemplates: new JwtTemplatesApi(request),
  oauthApplications: new OAuthApplicationsApi(request),

packages/backend/src/api/resources/APIKey.ts

@@ -0,0 +1,41 @@
+import type { APIKeyJSON } from './JSON';
+
+export class APIKey {
+ constructor(
+ readonly id: string,
+ readonly type: string,
+ readonly name: string,
+ readonly subject: string,
+ readonly scopes: string[],
+ readonly claims: Record<string, any> | null,
+ readonly revoked: boolean,
+ readonly revocationReason: string | null,
+ readonly expired: boolean,
+ readonly expiration: number | null,
+ readonly createdBy: string | null,
+ readonly description: string | null,
+ readonly lastUsedAt: number | null,
+ readonly createdAt: number,
+ readonly updatedAt: number,
+ ) {}
+
+ static fromJSON(data: APIKeyJSON) {
+ return new APIKey(
+ data.id,
+ data.type,
+ data.name,
+ data.subject,
+ data.scopes,
+ data.claims,
+ data.revoked,
+ data.revocation_reason,
+ data.expired,
+ data.expiration,
+ data.created_by,
+ data.description,
+ data.last_used_at,
+ data.created_at,
+ data.updated_at,
+ );
+ }
+}