chore(backend,nextjs): Introduce API keys methods and integration tests

.changeset/eighty-frogs-return.md

@@ -0,0 +1,5 @@
+---
+"@clerk/nextjs": minor
+---
+
+Fix `auth.protect()` unauthorized error propagation within middleware

.changeset/weak-adults-clean.md

@@ -0,0 +1,5 @@
+---
+"@clerk/backend": minor
+---
+
+Introduce API keys Backend SDK methods

integration/.keys.json.sample

@@ -54,5 +54,9 @@
  "with-whatsapp-phone-code": {
  "pk": "",
  "sk": ""
+ },
+ "with-api-keys": {
+ "pk": "",
+ "sk": ""
  }
 }

integration/presets/envs.ts

@@ -163,6 +163,12 @@ const withWhatsappPhoneCode = base
  .setEnvVariable('private', 'CLERK_SECRET_KEY', instanceKeys.get('with-whatsapp-phone-code').sk)
  .setEnvVariable('public', 'CLERK_PUBLISHABLE_KEY', instanceKeys.get('with-whatsapp-phone-code').pk);
 
+const withAPIKeys = base
+ .clone()
+ .setId('withAPIKeys')
+ .setEnvVariable('private', 'CLERK_SECRET_KEY', instanceKeys.get('with-api-keys').sk)
+ .setEnvVariable('public', 'CLERK_PUBLISHABLE_KEY', instanceKeys.get('with-api-keys').pk);
+
 export const envs = {
  base,
  withKeyless,
@@ -187,4 +193,5 @@ export const envs = {
  withBillingStaging,
  withBilling,
  withWhatsappPhoneCode,
+ withAPIKeys,
 } as const;

integration/presets/longRunningApps.ts

@@ -42,6 +42,7 @@ export const createLongRunningApps = () => {
  config: next.appRouter,
  env: envs.withSessionTasks,
  },
+ { id: 'next.appRouter.withAPIKeys', config: next.appRouter, env: envs.withAPIKeys },
  { id: 'withBillingStaging.next.appRouter', config: next.appRouter, env: envs.withBillingStaging },
  { id: 'withBilling.next.appRouter', config: next.appRouter, env: envs.withBilling },
  { id: 'withBillingStaging.vue.vite', config: vue.vite, env: envs.withBillingStaging },

integration/testUtils/index.ts

@@ -6,10 +6,10 @@ import type { Application } from '../models/application';
 import { createEmailService } from './emailService';
 import { createInvitationService } from './invitationsService';
 import { createOrganizationsService } from './organizationsService';
-import type { FakeOrganization, FakeUser } from './usersService';
+import type { FakeAPIKey, FakeOrganization, FakeUser } from './usersService';
 import { createUserService } from './usersService';
 
-export type { FakeUser, FakeOrganization };
+export type { FakeUser, FakeOrganization, FakeAPIKey };
 const createClerkClient = (app: Application) => {
  return backendCreateClerkClient({
  apiUrl: app.env.privateVariables.get('CLERK_API_URL'),

integration/testUtils/usersService.ts

@@ -1,4 +1,4 @@
-import type { ClerkClient, Organization, User } from '@clerk/backend';
+import type { APIKey, ClerkClient, Organization, User } from '@clerk/backend';
 import { faker } from '@faker-js/faker';
 
 import { hash } from '../models/helpers';
@@ -57,6 +57,12 @@ export type FakeOrganization = {
  delete: () => Promise<Organization>;
 };
 
+export type FakeAPIKey = {
+ apiKey: APIKey;
+ secret: string;
+ revoke: () => Promise<APIKey>;
+};
+
 export type UserService = {
  createFakeUser: (options?: FakeUserOptions) => FakeUser;
  createBapiUser: (fakeUser: FakeUser) => Promise<User>;
@@ -67,6 +73,7 @@ export type UserService = {
  deleteIfExists: (opts: { id?: string; email?: string; phoneNumber?: string }) => Promise<void>;
  createFakeOrganization: (userId: string) => Promise<FakeOrganization>;
  getUser: (opts: { id?: string; email?: string }) => Promise<User | undefined>;
+ createFakeAPIKey: (userId: string) => Promise<FakeAPIKey>;
 };
 
 /**
@@ -175,6 +182,23 @@ export const createUserService = (clerkClient: ClerkClient) => {
  delete: () => clerkClient.organizations.deleteOrganization(organization.id),
  } satisfies FakeOrganization;
  },
+ createFakeAPIKey: async (userId: string) => {
+ const TWENTY_MINUTES = 20 * 60;
+
+ const apiKey = await clerkClient.apiKeys.create({
+ subject: userId,
+ name: `Integration Test - ${userId}`,
+ secondsUntilExpiration: TWENTY_MINUTES,
+ });
+
+ const { secret } = await clerkClient.apiKeys.getSecret(apiKey.id);
+
+ return {
+ apiKey,
+ secret,
+ revoke: () => clerkClient.apiKeys.revoke({ apiKeyId: apiKey.id, revocationReason: 'For testing purposes' }),
+ } satisfies FakeAPIKey;
+ },
  };
 
  return self;

integration/tests/machine-auth/api-keys.test.ts

@@ -0,0 +1,214 @@
+import type { User } from '@clerk/backend';
+import { TokenType } from '@clerk/backend/internal';
+import { expect, test } from '@playwright/test';
+
+import type { Application } from '../../models/application';
+import { appConfigs } from '../../presets';
+import type { FakeAPIKey, FakeUser } from '../../testUtils';
+import { createTestUtils } from '../../testUtils';
+
+test.describe('Next.js API key auth within clerkMiddleware() @nextjs', () => {
+ test.describe.configure({ mode: 'parallel' });
+ let app: Application;
+ let fakeUser: FakeUser;
+ let fakeBapiUser: User;
+ let fakeAPIKey: FakeAPIKey;
+
+ test.beforeAll(async () => {
+ app = await appConfigs.next.appRouter
+ .clone()
+ .addFile(
+ `src/middleware.ts`,
+ () => `
+ import { clerkMiddleware, createRouteMatcher } from '@clerk/nextjs/server';
+
+ const isProtectedRoute = createRouteMatcher(['/api(.*)']);
+
+ export default clerkMiddleware(async (auth, req) => {
+ if (isProtectedRoute(req)) {
+ await auth.protect({ token: 'api_key' });
+ }
+ });
+
+ export const config = {
+ matcher: [
+ '/((?!.*\\..*|_next).*)', // Don't run middleware on static files
+ '/', // Run middleware on index page
+ '/(api|trpc)(.*)',
+ ], // Run middleware on API routes
+ };
+ `,
+ )
+ .addFile(
+ 'src/app/api/me/route.ts',
+ () => `
+ import { auth } from '@clerk/nextjs/server';
+
+ export async function GET() {
+ const { userId, tokenType } = await auth({ acceptsToken: 'api_key' });
+
+ return Response.json({ userId, tokenType });
+ }
+ `,
+ )
+ .commit();
+
+ await app.setup();
+ await app.withEnv(appConfigs.envs.withAPIKeys);
+ await app.dev();
+
+ const u = createTestUtils({ app });
+ fakeUser = u.services.users.createFakeUser();
+ fakeBapiUser = await u.services.users.createBapiUser(fakeUser);
+ fakeAPIKey = await u.services.users.createFakeAPIKey(fakeBapiUser.id);
+ });
+
+ test.afterAll(async () => {
+ await fakeAPIKey.revoke();
+ await fakeUser.deleteIfExists();
+ await app.teardown();
+ });
+
+ test('should return 401 if no API key is provided', async ({ request }) => {
+ const url = new URL('/api/me', app.serverUrl);
+ const res = await request.get(url.toString());
+ expect(res.status()).toBe(401);
+ });
+
+ test('should return 401 if API key is invalid', async ({ request }) => {
+ const url = new URL('/api/me', app.serverUrl);
+ const res = await request.get(url.toString(), {
+ headers: { Authorization: 'Bearer invalid_key' },
+ });
+ expect(res.status()).toBe(401);
+ });
+
+ test('should return 200 with auth object if API key is valid', async ({ request }) => {
+ const url = new URL('/api/me', app.serverUrl);
+ const res = await request.get(url.toString(), {
+ headers: {
+ Authorization: `Bearer ${fakeAPIKey.secret}`,
+ },
+ });
+ const apiKeyData = await res.json();
+ expect(res.status()).toBe(200);
+ expect(apiKeyData.userId).toBe(fakeBapiUser.id);
+ expect(apiKeyData.tokenType).toBe(TokenType.ApiKey);
+ });
+});
+
+test.describe('Next.js API key auth within routes @nextjs', () => {
+ test.describe.configure({ mode: 'parallel' });
+ let app: Application;
+ let fakeUser: FakeUser;
+ let fakeBapiUser: User;
+ let fakeAPIKey: FakeAPIKey;
+
+ test.beforeAll(async () => {
+ app = await appConfigs.next.appRouter
+ .clone()
+ .addFile(
+ 'src/app/api/me/route.ts',
+ () => `
+ import { auth } from '@clerk/nextjs/server';
+
+ export async function GET() {
+ const { userId, tokenType } = await auth({ acceptsToken: 'api_key' });
+
+ if (!userId) {
+ return Response.json({ error: 'Unauthorized' }, { status: 401 });
+ }
+
+ return Response.json({ userId, tokenType });
+ }
+
+ export async function POST() {
+ const authObject = await auth({ acceptsToken: ['api_key', 'session_token'] });
+
+ if (!authObject.isAuthenticated) {
+ return Response.json({ error: 'Unauthorized' }, { status: 401 });
+ }
+
+ return Response.json({ userId: authObject.userId, tokenType: authObject.tokenType });
+ }
+ `,
+ )
+ .commit();
+
+ await app.setup();
+ await app.withEnv(appConfigs.envs.withAPIKeys);
+ await app.dev();
+
+ const u = createTestUtils({ app });
+ fakeUser = u.services.users.createFakeUser();
+ fakeBapiUser = await u.services.users.createBapiUser(fakeUser);
+ fakeAPIKey = await u.services.users.createFakeAPIKey(fakeBapiUser.id);
+ });
+
+ test.afterAll(async () => {
+ await fakeAPIKey.revoke();
+ await fakeUser.deleteIfExists();
+ await app.teardown();
+ });
+
+ test('should return 401 if no API key is provided', async ({ request }) => {
+ const url = new URL('/api/me', app.serverUrl);
+ const res = await request.get(url.toString());
+ expect(res.status()).toBe(401);
+ });
+
+ test('should return 401 if API key is invalid', async ({ request }) => {
+ const url = new URL('/api/me', app.serverUrl);
+ const res = await request.get(url.toString(), {
+ headers: { Authorization: 'Bearer invalid_key' },
+ });
+ expect(res.status()).toBe(401);
+ });
+
+ test('should return 200 with auth object if API key is valid', async ({ request }) => {
+ const url = new URL('/api/me', app.serverUrl);
+ const res = await request.get(url.toString(), {
+ headers: {
+ Authorization: `Bearer ${fakeAPIKey.secret}`,
+ },
+ });
+ const apiKeyData = await res.json();
+ expect(res.status()).toBe(200);
+ expect(apiKeyData.userId).toBe(fakeBapiUser.id);
+ expect(apiKeyData.tokenType).toBe(TokenType.ApiKey);
+ });
+
+ test('should handle multiple token types', async ({ page, context }) => {
+ const u = createTestUtils({ app, page, context });
+ const url = new URL('/api/me', app.serverUrl);
+
+ // Sign in to get a session token
+ await u.po.signIn.goTo();
+ await u.po.signIn.waitForMounted();
+ await u.po.signIn.signInWithEmailAndInstantPassword({ email: fakeUser.email, password: fakeUser.password });
+ await u.po.expect.toBeSignedIn();
+
+ // GET endpoint (only accepts api_key)
+ const getRes = await u.page.request.get(url.toString());
+ expect(getRes.status()).toBe(401);
+
+ // POST endpoint (accepts both api_key and session_token)
+ // Test with session token
+ const postWithSessionRes = await u.page.request.post(url.toString());
+ const sessionData = await postWithSessionRes.json();
+ expect(postWithSessionRes.status()).toBe(200);
+ expect(sessionData.userId).toBe(fakeBapiUser.id);
+ expect(sessionData.tokenType).toBe(TokenType.SessionToken);
+
+ // Test with API key
+ const postWithApiKeyRes = await u.page.request.post(url.toString(), {
+ headers: {
+ Authorization: `Bearer ${fakeAPIKey.secret}`,
+ },
+ });
+ const apiKeyData = await postWithApiKeyRes.json();
+ expect(postWithApiKeyRes.status()).toBe(200);
+ expect(apiKeyData.userId).toBe(fakeBapiUser.id);
+ expect(apiKeyData.tokenType).toBe(TokenType.ApiKey);
+ });
+});

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

@@ -4,7 +4,67 @@ import { AbstractAPI } from './AbstractApi';
 
 const basePath = '/api_keys';
 
+type CreateAPIKeyParams = {
+ type?: 'api_key';
+ /**
+ * API key name
+ */
+ name: string;
+ /**
+ * user or organization ID the API key is associated with
+ */
+ subject: string;
+ /**
+ * API key description
+ */
+ description?: string | null;
+ claims?: Record<string, any> | null;
+ scopes?: string[];
+ createdBy?: string | null;
+ secondsUntilExpiration?: number | null;
+};
+
+type RevokeAPIKeyParams = {
+ /**
+ * API key ID
+ */
+ apiKeyId: string;
+ /**
+ * Reason for revocation
+ */
+ revocationReason?: string | null;
+};
+
 export class APIKeysAPI extends AbstractAPI {
+ async create(params: CreateAPIKeyParams) {
+ return this.request<APIKey>({
+ method: 'POST',
+ path: basePath,
+ bodyParams: params,
+ });
+ }
+
+ async revoke(params: RevokeAPIKeyParams) {
+ const { apiKeyId, ...bodyParams } = params;
+
+ this.requireId(apiKeyId);
+
+ return this.request<APIKey>({
+ method: 'POST',
+ path: joinPaths(basePath, apiKeyId, 'revoke'),
+ bodyParams,
+ });
+ }
+
+ async getSecret(apiKeyId: string) {
+ this.requireId(apiKeyId);
+
+ return this.request<{ secret: string }>({
+ method: 'GET',
+ path: joinPaths(basePath, apiKeyId, 'secret'),
+ });
+ }
+
  async verifySecret(secret: string) {
  return this.request<APIKey>({
  method: 'POST',

.changeset/eighty-frogs-return.md

@@ -0,0 +1,5 @@
+---
+"@clerk/nextjs": minor
+---
+
+Fix `auth.protect()` unauthorized error propagation within middleware

.changeset/weak-adults-clean.md

@@ -0,0 +1,5 @@
+---
+"@clerk/backend": minor
+---
+
+Introduce API keys Backend SDK methods

integration/.keys.json.sample

@@ -54,5 +54,9 @@
  "with-whatsapp-phone-code": {
  "pk": "",
  "sk": ""
+ },
+ "with-api-keys": {
+ "pk": "",
+ "sk": ""
  }
 }

integration/presets/envs.ts

@@ -163,6 +163,12 @@ const withWhatsappPhoneCode = base
  .setEnvVariable('private', 'CLERK_SECRET_KEY', instanceKeys.get('with-whatsapp-phone-code').sk)
  .setEnvVariable('public', 'CLERK_PUBLISHABLE_KEY', instanceKeys.get('with-whatsapp-phone-code').pk);
 
+const withAPIKeys = base
+ .clone()
+ .setId('withAPIKeys')
+ .setEnvVariable('private', 'CLERK_SECRET_KEY', instanceKeys.get('with-api-keys').sk)
+ .setEnvVariable('public', 'CLERK_PUBLISHABLE_KEY', instanceKeys.get('with-api-keys').pk);
+
 export const envs = {
  base,
  withKeyless,
@@ -187,4 +193,5 @@ export const envs = {
  withBillingStaging,
  withBilling,
  withWhatsappPhoneCode,
+ withAPIKeys,
 } as const;

integration/presets/longRunningApps.ts

@@ -42,6 +42,7 @@ export const createLongRunningApps = () => {
  config: next.appRouter,
  env: envs.withSessionTasks,
  },
+ { id: 'next.appRouter.withAPIKeys', config: next.appRouter, env: envs.withAPIKeys },
  { id: 'withBillingStaging.next.appRouter', config: next.appRouter, env: envs.withBillingStaging },
  { id: 'withBilling.next.appRouter', config: next.appRouter, env: envs.withBilling },
  { id: 'withBillingStaging.vue.vite', config: vue.vite, env: envs.withBillingStaging },

integration/testUtils/index.ts

@@ -6,10 +6,10 @@ import type { Application } from '../models/application';
 import { createEmailService } from './emailService';
 import { createInvitationService } from './invitationsService';
 import { createOrganizationsService } from './organizationsService';
-import type { FakeOrganization, FakeUser } from './usersService';
+import type { FakeAPIKey, FakeOrganization, FakeUser } from './usersService';
 import { createUserService } from './usersService';
 
-export type { FakeUser, FakeOrganization };
+export type { FakeUser, FakeOrganization, FakeAPIKey };
 const createClerkClient = (app: Application) => {
  return backendCreateClerkClient({
  apiUrl: app.env.privateVariables.get('CLERK_API_URL'),

integration/testUtils/usersService.ts

@@ -1,4 +1,4 @@
-import type { ClerkClient, Organization, User } from '@clerk/backend';
+import type { APIKey, ClerkClient, Organization, User } from '@clerk/backend';
 import { faker } from '@faker-js/faker';
 
 import { hash } from '../models/helpers';
@@ -57,6 +57,12 @@ export type FakeOrganization = {
  delete: () => Promise<Organization>;
 };
 
+export type FakeAPIKey = {
+ apiKey: APIKey;
+ secret: string;
+ revoke: () => Promise<APIKey>;
+};
+
 export type UserService = {
  createFakeUser: (options?: FakeUserOptions) => FakeUser;
  createBapiUser: (fakeUser: FakeUser) => Promise<User>;
@@ -67,6 +73,7 @@ export type UserService = {
  deleteIfExists: (opts: { id?: string; email?: string; phoneNumber?: string }) => Promise<void>;
  createFakeOrganization: (userId: string) => Promise<FakeOrganization>;
  getUser: (opts: { id?: string; email?: string }) => Promise<User | undefined>;
+ createFakeAPIKey: (userId: string) => Promise<FakeAPIKey>;
 };
 
 /**
@@ -175,6 +182,23 @@ export const createUserService = (clerkClient: ClerkClient) => {
  delete: () => clerkClient.organizations.deleteOrganization(organization.id),
  } satisfies FakeOrganization;
  },
+ createFakeAPIKey: async (userId: string) => {
+ const TWENTY_MINUTES = 20 * 60;
+
+ const apiKey = await clerkClient.apiKeys.create({
+ subject: userId,
+ name: `Integration Test - ${userId}`,
+ secondsUntilExpiration: TWENTY_MINUTES,
+ });
+
+ const { secret } = await clerkClient.apiKeys.getSecret(apiKey.id);
+
+ return {
+ apiKey,
+ secret,
+ revoke: () => clerkClient.apiKeys.revoke({ apiKeyId: apiKey.id, revocationReason: 'For testing purposes' }),
+ } satisfies FakeAPIKey;
+ },
  };
 
  return self;

integration/tests/machine-auth/api-keys.test.ts

@@ -0,0 +1,214 @@
+import type { User } from '@clerk/backend';
+import { TokenType } from '@clerk/backend/internal';
+import { expect, test } from '@playwright/test';
+
+import type { Application } from '../../models/application';
+import { appConfigs } from '../../presets';
+import type { FakeAPIKey, FakeUser } from '../../testUtils';
+import { createTestUtils } from '../../testUtils';
+
+test.describe('Next.js API key auth within clerkMiddleware() @nextjs', () => {
+ test.describe.configure({ mode: 'parallel' });
+ let app: Application;
+ let fakeUser: FakeUser;
+ let fakeBapiUser: User;
+ let fakeAPIKey: FakeAPIKey;
+
+ test.beforeAll(async () => {
+ app = await appConfigs.next.appRouter
+ .clone()
+ .addFile(
+ `src/middleware.ts`,
+ () => `
+ import { clerkMiddleware, createRouteMatcher } from '@clerk/nextjs/server';
+
+ const isProtectedRoute = createRouteMatcher(['/api(.*)']);
+
+ export default clerkMiddleware(async (auth, req) => {
+ if (isProtectedRoute(req)) {
+ await auth.protect({ token: 'api_key' });
+ }
+ });
+
+ export const config = {
+ matcher: [
+ '/((?!.*\\..*|_next).*)', // Don't run middleware on static files
+ '/', // Run middleware on index page
+ '/(api|trpc)(.*)',
+ ], // Run middleware on API routes
+ };
+ `,
+ )
+ .addFile(
+ 'src/app/api/me/route.ts',
+ () => `
+ import { auth } from '@clerk/nextjs/server';
+
+ export async function GET() {
+ const { userId, tokenType } = await auth({ acceptsToken: 'api_key' });
+
+ return Response.json({ userId, tokenType });
+ }
+ `,
+ )
+ .commit();
+
+ await app.setup();
+ await app.withEnv(appConfigs.envs.withAPIKeys);
+ await app.dev();
+
+ const u = createTestUtils({ app });
+ fakeUser = u.services.users.createFakeUser();
+ fakeBapiUser = await u.services.users.createBapiUser(fakeUser);
+ fakeAPIKey = await u.services.users.createFakeAPIKey(fakeBapiUser.id);
+ });
+
+ test.afterAll(async () => {
+ await fakeAPIKey.revoke();
+ await fakeUser.deleteIfExists();
+ await app.teardown();
+ });
+
+ test('should return 401 if no API key is provided', async ({ request }) => {
+ const url = new URL('/api/me', app.serverUrl);
+ const res = await request.get(url.toString());
+ expect(res.status()).toBe(401);
+ });
+
+ test('should return 401 if API key is invalid', async ({ request }) => {
+ const url = new URL('/api/me', app.serverUrl);
+ const res = await request.get(url.toString(), {
+ headers: { Authorization: 'Bearer invalid_key' },
+ });
+ expect(res.status()).toBe(401);
+ });
+
+ test('should return 200 with auth object if API key is valid', async ({ request }) => {
+ const url = new URL('/api/me', app.serverUrl);
+ const res = await request.get(url.toString(), {
+ headers: {
+ Authorization: `Bearer ${fakeAPIKey.secret}`,
+ },
+ });
+ const apiKeyData = await res.json();
+ expect(res.status()).toBe(200);
+ expect(apiKeyData.userId).toBe(fakeBapiUser.id);
+ expect(apiKeyData.tokenType).toBe(TokenType.ApiKey);
+ });
+});
+
+test.describe('Next.js API key auth within routes @nextjs', () => {
+ test.describe.configure({ mode: 'parallel' });
+ let app: Application;
+ let fakeUser: FakeUser;
+ let fakeBapiUser: User;
+ let fakeAPIKey: FakeAPIKey;
+
+ test.beforeAll(async () => {
+ app = await appConfigs.next.appRouter
+ .clone()
+ .addFile(
+ 'src/app/api/me/route.ts',
+ () => `
+ import { auth } from '@clerk/nextjs/server';
+
+ export async function GET() {
+ const { userId, tokenType } = await auth({ acceptsToken: 'api_key' });
+
+ if (!userId) {
+ return Response.json({ error: 'Unauthorized' }, { status: 401 });
+ }
+
+ return Response.json({ userId, tokenType });
+ }
+
+ export async function POST() {
+ const authObject = await auth({ acceptsToken: ['api_key', 'session_token'] });
+
+ if (!authObject.isAuthenticated) {
+ return Response.json({ error: 'Unauthorized' }, { status: 401 });
+ }
+
+ return Response.json({ userId: authObject.userId, tokenType: authObject.tokenType });
+ }
+ `,
+ )
+ .commit();
+
+ await app.setup();
+ await app.withEnv(appConfigs.envs.withAPIKeys);
+ await app.dev();
+
+ const u = createTestUtils({ app });
+ fakeUser = u.services.users.createFakeUser();
+ fakeBapiUser = await u.services.users.createBapiUser(fakeUser);
+ fakeAPIKey = await u.services.users.createFakeAPIKey(fakeBapiUser.id);
+ });
+
+ test.afterAll(async () => {
+ await fakeAPIKey.revoke();
+ await fakeUser.deleteIfExists();
+ await app.teardown();
+ });
+
+ test('should return 401 if no API key is provided', async ({ request }) => {
+ const url = new URL('/api/me', app.serverUrl);
+ const res = await request.get(url.toString());
+ expect(res.status()).toBe(401);
+ });
+
+ test('should return 401 if API key is invalid', async ({ request }) => {
+ const url = new URL('/api/me', app.serverUrl);
+ const res = await request.get(url.toString(), {
+ headers: { Authorization: 'Bearer invalid_key' },
+ });
+ expect(res.status()).toBe(401);
+ });
+
+ test('should return 200 with auth object if API key is valid', async ({ request }) => {
+ const url = new URL('/api/me', app.serverUrl);
+ const res = await request.get(url.toString(), {
+ headers: {
+ Authorization: `Bearer ${fakeAPIKey.secret}`,
+ },
+ });
+ const apiKeyData = await res.json();
+ expect(res.status()).toBe(200);
+ expect(apiKeyData.userId).toBe(fakeBapiUser.id);
+ expect(apiKeyData.tokenType).toBe(TokenType.ApiKey);
+ });
+
+ test('should handle multiple token types', async ({ page, context }) => {
+ const u = createTestUtils({ app, page, context });
+ const url = new URL('/api/me', app.serverUrl);
+
+ // Sign in to get a session token
+ await u.po.signIn.goTo();
+ await u.po.signIn.waitForMounted();
+ await u.po.signIn.signInWithEmailAndInstantPassword({ email: fakeUser.email, password: fakeUser.password });
+ await u.po.expect.toBeSignedIn();
+
+ // GET endpoint (only accepts api_key)
+ const getRes = await u.page.request.get(url.toString());
+ expect(getRes.status()).toBe(401);
+
+ // POST endpoint (accepts both api_key and session_token)
+ // Test with session token
+ const postWithSessionRes = await u.page.request.post(url.toString());
+ const sessionData = await postWithSessionRes.json();
+ expect(postWithSessionRes.status()).toBe(200);
+ expect(sessionData.userId).toBe(fakeBapiUser.id);
+ expect(sessionData.tokenType).toBe(TokenType.SessionToken);
+
+ // Test with API key
+ const postWithApiKeyRes = await u.page.request.post(url.toString(), {
+ headers: {
+ Authorization: `Bearer ${fakeAPIKey.secret}`,
+ },
+ });
+ const apiKeyData = await postWithApiKeyRes.json();
+ expect(postWithApiKeyRes.status()).toBe(200);
+ expect(apiKeyData.userId).toBe(fakeBapiUser.id);
+ expect(apiKeyData.tokenType).toBe(TokenType.ApiKey);
+ });
+});

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

@@ -4,7 +4,67 @@ import { AbstractAPI } from './AbstractApi';
 
 const basePath = '/api_keys';
 
+type CreateAPIKeyParams = {
+ type?: 'api_key';
+ /**
+ * API key name
+ */
+ name: string;
+ /**
+ * user or organization ID the API key is associated with
+ */
+ subject: string;
+ /**
+ * API key description
+ */
+ description?: string | null;
+ claims?: Record<string, any> | null;
+ scopes?: string[];
+ createdBy?: string | null;
+ secondsUntilExpiration?: number | null;
+};
+
+type RevokeAPIKeyParams = {
+ /**
+ * API key ID
+ */
+ apiKeyId: string;
+ /**
+ * Reason for revocation
+ */
+ revocationReason?: string | null;
+};
+
 export class APIKeysAPI extends AbstractAPI {
+ async create(params: CreateAPIKeyParams) {
+ return this.request<APIKey>({
+ method: 'POST',
+ path: basePath,
+ bodyParams: params,
+ });
+ }
+
+ async revoke(params: RevokeAPIKeyParams) {
+ const { apiKeyId, ...bodyParams } = params;
+
+ this.requireId(apiKeyId);
+
+ return this.request<APIKey>({
+ method: 'POST',
+ path: joinPaths(basePath, apiKeyId, 'revoke'),
+ bodyParams,
+ });
+ }
+
+ async getSecret(apiKeyId: string) {
+ this.requireId(apiKeyId);
+
+ return this.request<{ secret: string }>({
+ method: 'GET',
+ path: joinPaths(basePath, apiKeyId, 'secret'),
+ });
+ }
+
  async verifySecret(secret: string) {
  return this.request<APIKey>({
  method: 'POST',

.changeset/eighty-frogs-return.md

@@ -0,0 +1,5 @@
+---
+"@clerk/nextjs": minor
+---
+
+Fix `auth.protect()` unauthorized error propagation within middleware

.changeset/weak-adults-clean.md

@@ -0,0 +1,5 @@
+---
+"@clerk/backend": minor
+---
+
+Introduce API keys Backend SDK methods

integration/.keys.json.sample

@@ -54,5 +54,9 @@
  "with-whatsapp-phone-code": {
  "pk": "",
  "sk": ""
+ },
+ "with-api-keys": {
+ "pk": "",
+ "sk": ""
  }
 }

integration/presets/envs.ts

@@ -163,6 +163,12 @@ const withWhatsappPhoneCode = base
  .setEnvVariable('private', 'CLERK_SECRET_KEY', instanceKeys.get('with-whatsapp-phone-code').sk)
  .setEnvVariable('public', 'CLERK_PUBLISHABLE_KEY', instanceKeys.get('with-whatsapp-phone-code').pk);
 
+const withAPIKeys = base
+ .clone()
+ .setId('withAPIKeys')
+ .setEnvVariable('private', 'CLERK_SECRET_KEY', instanceKeys.get('with-api-keys').sk)
+ .setEnvVariable('public', 'CLERK_PUBLISHABLE_KEY', instanceKeys.get('with-api-keys').pk);
+
 export const envs = {
  base,
  withKeyless,
@@ -187,4 +193,5 @@ export const envs = {
  withBillingStaging,
  withBilling,
  withWhatsappPhoneCode,
+ withAPIKeys,
 } as const;

integration/presets/longRunningApps.ts

@@ -42,6 +42,7 @@ export const createLongRunningApps = () => {
  config: next.appRouter,
  env: envs.withSessionTasks,
  },
+ { id: 'next.appRouter.withAPIKeys', config: next.appRouter, env: envs.withAPIKeys },
  { id: 'withBillingStaging.next.appRouter', config: next.appRouter, env: envs.withBillingStaging },
  { id: 'withBilling.next.appRouter', config: next.appRouter, env: envs.withBilling },
  { id: 'withBillingStaging.vue.vite', config: vue.vite, env: envs.withBillingStaging },

integration/testUtils/index.ts

@@ -6,10 +6,10 @@ import type { Application } from '../models/application';
 import { createEmailService } from './emailService';
 import { createInvitationService } from './invitationsService';
 import { createOrganizationsService } from './organizationsService';
-import type { FakeOrganization, FakeUser } from './usersService';
+import type { FakeAPIKey, FakeOrganization, FakeUser } from './usersService';
 import { createUserService } from './usersService';
 
-export type { FakeUser, FakeOrganization };
+export type { FakeUser, FakeOrganization, FakeAPIKey };
 const createClerkClient = (app: Application) => {
  return backendCreateClerkClient({
  apiUrl: app.env.privateVariables.get('CLERK_API_URL'),

integration/testUtils/usersService.ts

@@ -1,4 +1,4 @@
-import type { ClerkClient, Organization, User } from '@clerk/backend';
+import type { APIKey, ClerkClient, Organization, User } from '@clerk/backend';
 import { faker } from '@faker-js/faker';
 
 import { hash } from '../models/helpers';
@@ -57,6 +57,12 @@ export type FakeOrganization = {
  delete: () => Promise<Organization>;
 };
 
+export type FakeAPIKey = {
+ apiKey: APIKey;
+ secret: string;
+ revoke: () => Promise<APIKey>;
+};
+
 export type UserService = {
  createFakeUser: (options?: FakeUserOptions) => FakeUser;
  createBapiUser: (fakeUser: FakeUser) => Promise<User>;
@@ -67,6 +73,7 @@ export type UserService = {
  deleteIfExists: (opts: { id?: string; email?: string; phoneNumber?: string }) => Promise<void>;
  createFakeOrganization: (userId: string) => Promise<FakeOrganization>;
  getUser: (opts: { id?: string; email?: string }) => Promise<User | undefined>;
+ createFakeAPIKey: (userId: string) => Promise<FakeAPIKey>;
 };
 
 /**
@@ -175,6 +182,23 @@ export const createUserService = (clerkClient: ClerkClient) => {
  delete: () => clerkClient.organizations.deleteOrganization(organization.id),
  } satisfies FakeOrganization;
  },
+ createFakeAPIKey: async (userId: string) => {
+ const TWENTY_MINUTES = 20 * 60;
+
+ const apiKey = await clerkClient.apiKeys.create({
+ subject: userId,
+ name: `Integration Test - ${userId}`,
+ secondsUntilExpiration: TWENTY_MINUTES,
+ });
+
+ const { secret } = await clerkClient.apiKeys.getSecret(apiKey.id);
+
+ return {
+ apiKey,
+ secret,
+ revoke: () => clerkClient.apiKeys.revoke({ apiKeyId: apiKey.id, revocationReason: 'For testing purposes' }),
+ } satisfies FakeAPIKey;
+ },
  };
 
  return self;

integration/tests/machine-auth/api-keys.test.ts

@@ -0,0 +1,214 @@
+import type { User } from '@clerk/backend';
+import { TokenType } from '@clerk/backend/internal';
+import { expect, test } from '@playwright/test';
+
+import type { Application } from '../../models/application';
+import { appConfigs } from '../../presets';
+import type { FakeAPIKey, FakeUser } from '../../testUtils';
+import { createTestUtils } from '../../testUtils';
+
+test.describe('Next.js API key auth within clerkMiddleware() @nextjs', () => {
+ test.describe.configure({ mode: 'parallel' });
+ let app: Application;
+ let fakeUser: FakeUser;
+ let fakeBapiUser: User;
+ let fakeAPIKey: FakeAPIKey;
+
+ test.beforeAll(async () => {
+ app = await appConfigs.next.appRouter
+ .clone()
+ .addFile(
+ `src/middleware.ts`,
+ () => `
+ import { clerkMiddleware, createRouteMatcher } from '@clerk/nextjs/server';
+
+ const isProtectedRoute = createRouteMatcher(['/api(.*)']);
+
+ export default clerkMiddleware(async (auth, req) => {
+ if (isProtectedRoute(req)) {
+ await auth.protect({ token: 'api_key' });
+ }
+ });
+
+ export const config = {
+ matcher: [
+ '/((?!.*\\..*|_next).*)', // Don't run middleware on static files
+ '/', // Run middleware on index page
+ '/(api|trpc)(.*)',
+ ], // Run middleware on API routes
+ };
+ `,
+ )
+ .addFile(
+ 'src/app/api/me/route.ts',
+ () => `
+ import { auth } from '@clerk/nextjs/server';
+
+ export async function GET() {
+ const { userId, tokenType } = await auth({ acceptsToken: 'api_key' });
+
+ return Response.json({ userId, tokenType });
+ }
+ `,
+ )
+ .commit();
+
+ await app.setup();
+ await app.withEnv(appConfigs.envs.withAPIKeys);
+ await app.dev();
+
+ const u = createTestUtils({ app });
+ fakeUser = u.services.users.createFakeUser();
+ fakeBapiUser = await u.services.users.createBapiUser(fakeUser);
+ fakeAPIKey = await u.services.users.createFakeAPIKey(fakeBapiUser.id);
+ });
+
+ test.afterAll(async () => {
+ await fakeAPIKey.revoke();
+ await fakeUser.deleteIfExists();
+ await app.teardown();
+ });
+
+ test('should return 401 if no API key is provided', async ({ request }) => {
+ const url = new URL('/api/me', app.serverUrl);
+ const res = await request.get(url.toString());
+ expect(res.status()).toBe(401);
+ });
+
+ test('should return 401 if API key is invalid', async ({ request }) => {
+ const url = new URL('/api/me', app.serverUrl);
+ const res = await request.get(url.toString(), {
+ headers: { Authorization: 'Bearer invalid_key' },
+ });
+ expect(res.status()).toBe(401);
+ });
+
+ test('should return 200 with auth object if API key is valid', async ({ request }) => {
+ const url = new URL('/api/me', app.serverUrl);
+ const res = await request.get(url.toString(), {
+ headers: {
+ Authorization: `Bearer ${fakeAPIKey.secret}`,
+ },
+ });
+ const apiKeyData = await res.json();
+ expect(res.status()).toBe(200);
+ expect(apiKeyData.userId).toBe(fakeBapiUser.id);
+ expect(apiKeyData.tokenType).toBe(TokenType.ApiKey);
+ });
+});
+
+test.describe('Next.js API key auth within routes @nextjs', () => {
+ test.describe.configure({ mode: 'parallel' });
+ let app: Application;
+ let fakeUser: FakeUser;
+ let fakeBapiUser: User;
+ let fakeAPIKey: FakeAPIKey;
+
+ test.beforeAll(async () => {
+ app = await appConfigs.next.appRouter
+ .clone()
+ .addFile(
+ 'src/app/api/me/route.ts',
+ () => `
+ import { auth } from '@clerk/nextjs/server';
+
+ export async function GET() {
+ const { userId, tokenType } = await auth({ acceptsToken: 'api_key' });
+
+ if (!userId) {
+ return Response.json({ error: 'Unauthorized' }, { status: 401 });
+ }
+
+ return Response.json({ userId, tokenType });
+ }
+
+ export async function POST() {
+ const authObject = await auth({ acceptsToken: ['api_key', 'session_token'] });
+
+ if (!authObject.isAuthenticated) {
+ return Response.json({ error: 'Unauthorized' }, { status: 401 });
+ }
+
+ return Response.json({ userId: authObject.userId, tokenType: authObject.tokenType });
+ }
+ `,
+ )
+ .commit();
+
+ await app.setup();
+ await app.withEnv(appConfigs.envs.withAPIKeys);
+ await app.dev();
+
+ const u = createTestUtils({ app });
+ fakeUser = u.services.users.createFakeUser();
+ fakeBapiUser = await u.services.users.createBapiUser(fakeUser);
+ fakeAPIKey = await u.services.users.createFakeAPIKey(fakeBapiUser.id);
+ });
+
+ test.afterAll(async () => {
+ await fakeAPIKey.revoke();
+ await fakeUser.deleteIfExists();
+ await app.teardown();
+ });
+
+ test('should return 401 if no API key is provided', async ({ request }) => {
+ const url = new URL('/api/me', app.serverUrl);
+ const res = await request.get(url.toString());
+ expect(res.status()).toBe(401);
+ });
+
+ test('should return 401 if API key is invalid', async ({ request }) => {
+ const url = new URL('/api/me', app.serverUrl);
+ const res = await request.get(url.toString(), {
+ headers: { Authorization: 'Bearer invalid_key' },
+ });
+ expect(res.status()).toBe(401);
+ });
+
+ test('should return 200 with auth object if API key is valid', async ({ request }) => {
+ const url = new URL('/api/me', app.serverUrl);
+ const res = await request.get(url.toString(), {
+ headers: {
+ Authorization: `Bearer ${fakeAPIKey.secret}`,
+ },
+ });
+ const apiKeyData = await res.json();
+ expect(res.status()).toBe(200);
+ expect(apiKeyData.userId).toBe(fakeBapiUser.id);
+ expect(apiKeyData.tokenType).toBe(TokenType.ApiKey);
+ });
+
+ test('should handle multiple token types', async ({ page, context }) => {
+ const u = createTestUtils({ app, page, context });
+ const url = new URL('/api/me', app.serverUrl);
+
+ // Sign in to get a session token
+ await u.po.signIn.goTo();
+ await u.po.signIn.waitForMounted();
+ await u.po.signIn.signInWithEmailAndInstantPassword({ email: fakeUser.email, password: fakeUser.password });
+ await u.po.expect.toBeSignedIn();
+
+ // GET endpoint (only accepts api_key)
+ const getRes = await u.page.request.get(url.toString());
+ expect(getRes.status()).toBe(401);
+
+ // POST endpoint (accepts both api_key and session_token)
+ // Test with session token
+ const postWithSessionRes = await u.page.request.post(url.toString());
+ const sessionData = await postWithSessionRes.json();
+ expect(postWithSessionRes.status()).toBe(200);
+ expect(sessionData.userId).toBe(fakeBapiUser.id);
+ expect(sessionData.tokenType).toBe(TokenType.SessionToken);
+
+ // Test with API key
+ const postWithApiKeyRes = await u.page.request.post(url.toString(), {
+ headers: {
+ Authorization: `Bearer ${fakeAPIKey.secret}`,
+ },
+ });
+ const apiKeyData = await postWithApiKeyRes.json();
+ expect(postWithApiKeyRes.status()).toBe(200);
+ expect(apiKeyData.userId).toBe(fakeBapiUser.id);
+ expect(apiKeyData.tokenType).toBe(TokenType.ApiKey);
+ });
+});

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

@@ -4,7 +4,67 @@ import { AbstractAPI } from './AbstractApi';
 
 const basePath = '/api_keys';
 
+type CreateAPIKeyParams = {
+ type?: 'api_key';
+ /**
+ * API key name
+ */
+ name: string;
+ /**
+ * user or organization ID the API key is associated with
+ */
+ subject: string;
+ /**
+ * API key description
+ */
+ description?: string | null;
+ claims?: Record<string, any> | null;
+ scopes?: string[];
+ createdBy?: string | null;
+ secondsUntilExpiration?: number | null;
+};
+
+type RevokeAPIKeyParams = {
+ /**
+ * API key ID
+ */
+ apiKeyId: string;
+ /**
+ * Reason for revocation
+ */
+ revocationReason?: string | null;
+};
+
 export class APIKeysAPI extends AbstractAPI {
+ async create(params: CreateAPIKeyParams) {
+ return this.request<APIKey>({
+ method: 'POST',
+ path: basePath,
+ bodyParams: params,
+ });
+ }
+
+ async revoke(params: RevokeAPIKeyParams) {
+ const { apiKeyId, ...bodyParams } = params;
+
+ this.requireId(apiKeyId);
+
+ return this.request<APIKey>({
+ method: 'POST',
+ path: joinPaths(basePath, apiKeyId, 'revoke'),
+ bodyParams,
+ });
+ }
+
+ async getSecret(apiKeyId: string) {
+ this.requireId(apiKeyId);
+
+ return this.request<{ secret: string }>({
+ method: 'GET',
+ path: joinPaths(basePath, apiKeyId, 'secret'),
+ });
+ }
+
  async verifySecret(secret: string) {
  return this.request<APIKey>({
  method: 'POST',

.changeset/eighty-frogs-return.md

@@ -0,0 +1,5 @@
+---
+"@clerk/nextjs": minor
+---
+
+Fix `auth.protect()` unauthorized error propagation within middleware

.changeset/weak-adults-clean.md

@@ -0,0 +1,5 @@
+---
+"@clerk/backend": minor
+---
+
+Introduce API keys Backend SDK methods

integration/.keys.json.sample

@@ -54,5 +54,9 @@
  "with-whatsapp-phone-code": {
  "pk": "",
  "sk": ""
+ },
+ "with-api-keys": {
+ "pk": "",
+ "sk": ""
  }
 }

integration/presets/envs.ts

@@ -163,6 +163,12 @@ const withWhatsappPhoneCode = base
  .setEnvVariable('private', 'CLERK_SECRET_KEY', instanceKeys.get('with-whatsapp-phone-code').sk)
  .setEnvVariable('public', 'CLERK_PUBLISHABLE_KEY', instanceKeys.get('with-whatsapp-phone-code').pk);
 
+const withAPIKeys = base
+ .clone()
+ .setId('withAPIKeys')
+ .setEnvVariable('private', 'CLERK_SECRET_KEY', instanceKeys.get('with-api-keys').sk)
+ .setEnvVariable('public', 'CLERK_PUBLISHABLE_KEY', instanceKeys.get('with-api-keys').pk);
+
 export const envs = {
  base,
  withKeyless,
@@ -187,4 +193,5 @@ export const envs = {
  withBillingStaging,
  withBilling,
  withWhatsappPhoneCode,
+ withAPIKeys,
 } as const;

integration/presets/longRunningApps.ts

@@ -42,6 +42,7 @@ export const createLongRunningApps = () => {
  config: next.appRouter,
  env: envs.withSessionTasks,
  },
+ { id: 'next.appRouter.withAPIKeys', config: next.appRouter, env: envs.withAPIKeys },
  { id: 'withBillingStaging.next.appRouter', config: next.appRouter, env: envs.withBillingStaging },
  { id: 'withBilling.next.appRouter', config: next.appRouter, env: envs.withBilling },
  { id: 'withBillingStaging.vue.vite', config: vue.vite, env: envs.withBillingStaging },

integration/testUtils/index.ts

@@ -6,10 +6,10 @@ import type { Application } from '../models/application';
 import { createEmailService } from './emailService';
 import { createInvitationService } from './invitationsService';
 import { createOrganizationsService } from './organizationsService';
-import type { FakeOrganization, FakeUser } from './usersService';
+import type { FakeAPIKey, FakeOrganization, FakeUser } from './usersService';
 import { createUserService } from './usersService';
 
-export type { FakeUser, FakeOrganization };
+export type { FakeUser, FakeOrganization, FakeAPIKey };
 const createClerkClient = (app: Application) => {
  return backendCreateClerkClient({
  apiUrl: app.env.privateVariables.get('CLERK_API_URL'),

integration/testUtils/usersService.ts

@@ -1,4 +1,4 @@
-import type { ClerkClient, Organization, User } from '@clerk/backend';
+import type { APIKey, ClerkClient, Organization, User } from '@clerk/backend';
 import { faker } from '@faker-js/faker';
 
 import { hash } from '../models/helpers';
@@ -57,6 +57,12 @@ export type FakeOrganization = {
  delete: () => Promise<Organization>;
 };
 
+export type FakeAPIKey = {
+ apiKey: APIKey;
+ secret: string;
+ revoke: () => Promise<APIKey>;
+};
+
 export type UserService = {
  createFakeUser: (options?: FakeUserOptions) => FakeUser;
  createBapiUser: (fakeUser: FakeUser) => Promise<User>;
@@ -67,6 +73,7 @@ export type UserService = {
  deleteIfExists: (opts: { id?: string; email?: string; phoneNumber?: string }) => Promise<void>;
  createFakeOrganization: (userId: string) => Promise<FakeOrganization>;
  getUser: (opts: { id?: string; email?: string }) => Promise<User | undefined>;
+ createFakeAPIKey: (userId: string) => Promise<FakeAPIKey>;
 };
 
 /**
@@ -175,6 +182,23 @@ export const createUserService = (clerkClient: ClerkClient) => {
  delete: () => clerkClient.organizations.deleteOrganization(organization.id),
  } satisfies FakeOrganization;
  },
+ createFakeAPIKey: async (userId: string) => {
+ const TWENTY_MINUTES = 20 * 60;
+
+ const apiKey = await clerkClient.apiKeys.create({
+ subject: userId,
+ name: `Integration Test - ${userId}`,
+ secondsUntilExpiration: TWENTY_MINUTES,
+ });
+
+ const { secret } = await clerkClient.apiKeys.getSecret(apiKey.id);
+
+ return {
+ apiKey,
+ secret,
+ revoke: () => clerkClient.apiKeys.revoke({ apiKeyId: apiKey.id, revocationReason: 'For testing purposes' }),
+ } satisfies FakeAPIKey;
+ },
  };
 
  return self;

integration/tests/machine-auth/api-keys.test.ts

@@ -0,0 +1,214 @@
+import type { User } from '@clerk/backend';
+import { TokenType } from '@clerk/backend/internal';
+import { expect, test } from '@playwright/test';
+
+import type { Application } from '../../models/application';
+import { appConfigs } from '../../presets';
+import type { FakeAPIKey, FakeUser } from '../../testUtils';
+import { createTestUtils } from '../../testUtils';
+
+test.describe('Next.js API key auth within clerkMiddleware() @nextjs', () => {
+ test.describe.configure({ mode: 'parallel' });
+ let app: Application;
+ let fakeUser: FakeUser;
+ let fakeBapiUser: User;
+ let fakeAPIKey: FakeAPIKey;
+
+ test.beforeAll(async () => {
+ app = await appConfigs.next.appRouter
+ .clone()
+ .addFile(
+ `src/middleware.ts`,
+ () => `
+ import { clerkMiddleware, createRouteMatcher } from '@clerk/nextjs/server';
+
+ const isProtectedRoute = createRouteMatcher(['/api(.*)']);
+
+ export default clerkMiddleware(async (auth, req) => {
+ if (isProtectedRoute(req)) {
+ await auth.protect({ token: 'api_key' });
+ }
+ });
+
+ export const config = {
+ matcher: [
+ '/((?!.*\\..*|_next).*)', // Don't run middleware on static files
+ '/', // Run middleware on index page
+ '/(api|trpc)(.*)',
+ ], // Run middleware on API routes
+ };
+ `,
+ )
+ .addFile(
+ 'src/app/api/me/route.ts',
+ () => `
+ import { auth } from '@clerk/nextjs/server';
+
+ export async function GET() {
+ const { userId, tokenType } = await auth({ acceptsToken: 'api_key' });
+
+ return Response.json({ userId, tokenType });
+ }
+ `,
+ )
+ .commit();
+
+ await app.setup();
+ await app.withEnv(appConfigs.envs.withAPIKeys);
+ await app.dev();
+
+ const u = createTestUtils({ app });
+ fakeUser = u.services.users.createFakeUser();
+ fakeBapiUser = await u.services.users.createBapiUser(fakeUser);
+ fakeAPIKey = await u.services.users.createFakeAPIKey(fakeBapiUser.id);
+ });
+
+ test.afterAll(async () => {
+ await fakeAPIKey.revoke();
+ await fakeUser.deleteIfExists();
+ await app.teardown();
+ });
+
+ test('should return 401 if no API key is provided', async ({ request }) => {
+ const url = new URL('/api/me', app.serverUrl);
+ const res = await request.get(url.toString());
+ expect(res.status()).toBe(401);
+ });
+
+ test('should return 401 if API key is invalid', async ({ request }) => {
+ const url = new URL('/api/me', app.serverUrl);
+ const res = await request.get(url.toString(), {
+ headers: { Authorization: 'Bearer invalid_key' },
+ });
+ expect(res.status()).toBe(401);
+ });
+
+ test('should return 200 with auth object if API key is valid', async ({ request }) => {
+ const url = new URL('/api/me', app.serverUrl);
+ const res = await request.get(url.toString(), {
+ headers: {
+ Authorization: `Bearer ${fakeAPIKey.secret}`,
+ },
+ });
+ const apiKeyData = await res.json();
+ expect(res.status()).toBe(200);
+ expect(apiKeyData.userId).toBe(fakeBapiUser.id);
+ expect(apiKeyData.tokenType).toBe(TokenType.ApiKey);
+ });
+});
+
+test.describe('Next.js API key auth within routes @nextjs', () => {
+ test.describe.configure({ mode: 'parallel' });
+ let app: Application;
+ let fakeUser: FakeUser;
+ let fakeBapiUser: User;
+ let fakeAPIKey: FakeAPIKey;
+
+ test.beforeAll(async () => {
+ app = await appConfigs.next.appRouter
+ .clone()
+ .addFile(
+ 'src/app/api/me/route.ts',
+ () => `
+ import { auth } from '@clerk/nextjs/server';
+
+ export async function GET() {
+ const { userId, tokenType } = await auth({ acceptsToken: 'api_key' });
+
+ if (!userId) {
+ return Response.json({ error: 'Unauthorized' }, { status: 401 });
+ }
+
+ return Response.json({ userId, tokenType });
+ }
+
+ export async function POST() {
+ const authObject = await auth({ acceptsToken: ['api_key', 'session_token'] });
+
+ if (!authObject.isAuthenticated) {
+ return Response.json({ error: 'Unauthorized' }, { status: 401 });
+ }
+
+ return Response.json({ userId: authObject.userId, tokenType: authObject.tokenType });
+ }
+ `,
+ )
+ .commit();
+
+ await app.setup();
+ await app.withEnv(appConfigs.envs.withAPIKeys);
+ await app.dev();
+
+ const u = createTestUtils({ app });
+ fakeUser = u.services.users.createFakeUser();
+ fakeBapiUser = await u.services.users.createBapiUser(fakeUser);
+ fakeAPIKey = await u.services.users.createFakeAPIKey(fakeBapiUser.id);
+ });
+
+ test.afterAll(async () => {
+ await fakeAPIKey.revoke();
+ await fakeUser.deleteIfExists();
+ await app.teardown();
+ });
+
+ test('should return 401 if no API key is provided', async ({ request }) => {
+ const url = new URL('/api/me', app.serverUrl);
+ const res = await request.get(url.toString());
+ expect(res.status()).toBe(401);
+ });
+
+ test('should return 401 if API key is invalid', async ({ request }) => {
+ const url = new URL('/api/me', app.serverUrl);
+ const res = await request.get(url.toString(), {
+ headers: { Authorization: 'Bearer invalid_key' },
+ });
+ expect(res.status()).toBe(401);
+ });
+
+ test('should return 200 with auth object if API key is valid', async ({ request }) => {
+ const url = new URL('/api/me', app.serverUrl);
+ const res = await request.get(url.toString(), {
+ headers: {
+ Authorization: `Bearer ${fakeAPIKey.secret}`,
+ },
+ });
+ const apiKeyData = await res.json();
+ expect(res.status()).toBe(200);
+ expect(apiKeyData.userId).toBe(fakeBapiUser.id);
+ expect(apiKeyData.tokenType).toBe(TokenType.ApiKey);
+ });
+
+ test('should handle multiple token types', async ({ page, context }) => {
+ const u = createTestUtils({ app, page, context });
+ const url = new URL('/api/me', app.serverUrl);
+
+ // Sign in to get a session token
+ await u.po.signIn.goTo();
+ await u.po.signIn.waitForMounted();
+ await u.po.signIn.signInWithEmailAndInstantPassword({ email: fakeUser.email, password: fakeUser.password });
+ await u.po.expect.toBeSignedIn();
+
+ // GET endpoint (only accepts api_key)
+ const getRes = await u.page.request.get(url.toString());
+ expect(getRes.status()).toBe(401);
+
+ // POST endpoint (accepts both api_key and session_token)
+ // Test with session token
+ const postWithSessionRes = await u.page.request.post(url.toString());
+ const sessionData = await postWithSessionRes.json();
+ expect(postWithSessionRes.status()).toBe(200);
+ expect(sessionData.userId).toBe(fakeBapiUser.id);
+ expect(sessionData.tokenType).toBe(TokenType.SessionToken);
+
+ // Test with API key
+ const postWithApiKeyRes = await u.page.request.post(url.toString(), {
+ headers: {
+ Authorization: `Bearer ${fakeAPIKey.secret}`,
+ },
+ });
+ const apiKeyData = await postWithApiKeyRes.json();
+ expect(postWithApiKeyRes.status()).toBe(200);
+ expect(apiKeyData.userId).toBe(fakeBapiUser.id);
+ expect(apiKeyData.tokenType).toBe(TokenType.ApiKey);
+ });
+});

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

@@ -4,7 +4,67 @@ import { AbstractAPI } from './AbstractApi';
 
 const basePath = '/api_keys';
 
+type CreateAPIKeyParams = {
+ type?: 'api_key';
+ /**
+ * API key name
+ */
+ name: string;
+ /**
+ * user or organization ID the API key is associated with
+ */
+ subject: string;
+ /**
+ * API key description
+ */
+ description?: string | null;
+ claims?: Record<string, any> | null;
+ scopes?: string[];
+ createdBy?: string | null;
+ secondsUntilExpiration?: number | null;
+};
+
+type RevokeAPIKeyParams = {
+ /**
+ * API key ID
+ */
+ apiKeyId: string;
+ /**
+ * Reason for revocation
+ */
+ revocationReason?: string | null;
+};
+
 export class APIKeysAPI extends AbstractAPI {
+ async create(params: CreateAPIKeyParams) {
+ return this.request<APIKey>({
+ method: 'POST',
+ path: basePath,
+ bodyParams: params,
+ });
+ }
+
+ async revoke(params: RevokeAPIKeyParams) {
+ const { apiKeyId, ...bodyParams } = params;
+
+ this.requireId(apiKeyId);
+
+ return this.request<APIKey>({
+ method: 'POST',
+ path: joinPaths(basePath, apiKeyId, 'revoke'),
+ bodyParams,
+ });
+ }
+
+ async getSecret(apiKeyId: string) {
+ this.requireId(apiKeyId);
+
+ return this.request<{ secret: string }>({
+ method: 'GET',
+ path: joinPaths(basePath, apiKeyId, 'secret'),
+ });
+ }
+
  async verifySecret(secret: string) {
  return this.request<APIKey>({
  method: 'POST',

.changeset/eighty-frogs-return.md

@@ -0,0 +1,5 @@
+---
+"@clerk/nextjs": minor
+---
+
+Fix `auth.protect()` unauthorized error propagation within middleware

.changeset/weak-adults-clean.md

@@ -0,0 +1,5 @@
+---
+"@clerk/backend": minor
+---
+
+Introduce API keys Backend SDK methods

integration/.keys.json.sample

@@ -54,5 +54,9 @@
  "with-whatsapp-phone-code": {
  "pk": "",
  "sk": ""
+ },
+ "with-api-keys": {
+ "pk": "",
+ "sk": ""
  }
 }

integration/presets/envs.ts

@@ -163,6 +163,12 @@ const withWhatsappPhoneCode = base
  .setEnvVariable('private', 'CLERK_SECRET_KEY', instanceKeys.get('with-whatsapp-phone-code').sk)
  .setEnvVariable('public', 'CLERK_PUBLISHABLE_KEY', instanceKeys.get('with-whatsapp-phone-code').pk);
 
+const withAPIKeys = base
+ .clone()
+ .setId('withAPIKeys')
+ .setEnvVariable('private', 'CLERK_SECRET_KEY', instanceKeys.get('with-api-keys').sk)
+ .setEnvVariable('public', 'CLERK_PUBLISHABLE_KEY', instanceKeys.get('with-api-keys').pk);
+
 export const envs = {
  base,
  withKeyless,
@@ -187,4 +193,5 @@ export const envs = {
  withBillingStaging,
  withBilling,
  withWhatsappPhoneCode,
+ withAPIKeys,
 } as const;

integration/presets/longRunningApps.ts

@@ -42,6 +42,7 @@ export const createLongRunningApps = () => {
  config: next.appRouter,
  env: envs.withSessionTasks,
  },
+ { id: 'next.appRouter.withAPIKeys', config: next.appRouter, env: envs.withAPIKeys },
  { id: 'withBillingStaging.next.appRouter', config: next.appRouter, env: envs.withBillingStaging },
  { id: 'withBilling.next.appRouter', config: next.appRouter, env: envs.withBilling },
  { id: 'withBillingStaging.vue.vite', config: vue.vite, env: envs.withBillingStaging },

integration/testUtils/index.ts

@@ -6,10 +6,10 @@ import type { Application } from '../models/application';
 import { createEmailService } from './emailService';
 import { createInvitationService } from './invitationsService';
 import { createOrganizationsService } from './organizationsService';
-import type { FakeOrganization, FakeUser } from './usersService';
+import type { FakeAPIKey, FakeOrganization, FakeUser } from './usersService';
 import { createUserService } from './usersService';
 
-export type { FakeUser, FakeOrganization };
+export type { FakeUser, FakeOrganization, FakeAPIKey };
 const createClerkClient = (app: Application) => {
  return backendCreateClerkClient({
  apiUrl: app.env.privateVariables.get('CLERK_API_URL'),

integration/testUtils/usersService.ts

@@ -1,4 +1,4 @@
-import type { ClerkClient, Organization, User } from '@clerk/backend';
+import type { APIKey, ClerkClient, Organization, User } from '@clerk/backend';
 import { faker } from '@faker-js/faker';
 
 import { hash } from '../models/helpers';
@@ -57,6 +57,12 @@ export type FakeOrganization = {
  delete: () => Promise<Organization>;
 };
 
+export type FakeAPIKey = {
+ apiKey: APIKey;
+ secret: string;
+ revoke: () => Promise<APIKey>;
+};
+
 export type UserService = {
  createFakeUser: (options?: FakeUserOptions) => FakeUser;
  createBapiUser: (fakeUser: FakeUser) => Promise<User>;
@@ -67,6 +73,7 @@ export type UserService = {
  deleteIfExists: (opts: { id?: string; email?: string; phoneNumber?: string }) => Promise<void>;
  createFakeOrganization: (userId: string) => Promise<FakeOrganization>;
  getUser: (opts: { id?: string; email?: string }) => Promise<User | undefined>;
+ createFakeAPIKey: (userId: string) => Promise<FakeAPIKey>;
 };
 
 /**
@@ -175,6 +182,23 @@ export const createUserService = (clerkClient: ClerkClient) => {
  delete: () => clerkClient.organizations.deleteOrganization(organization.id),
  } satisfies FakeOrganization;
  },
+ createFakeAPIKey: async (userId: string) => {
+ const TWENTY_MINUTES = 20 * 60;
+
+ const apiKey = await clerkClient.apiKeys.create({
+ subject: userId,
+ name: `Integration Test - ${userId}`,
+ secondsUntilExpiration: TWENTY_MINUTES,
+ });
+
+ const { secret } = await clerkClient.apiKeys.getSecret(apiKey.id);
+
+ return {
+ apiKey,
+ secret,
+ revoke: () => clerkClient.apiKeys.revoke({ apiKeyId: apiKey.id, revocationReason: 'For testing purposes' }),
+ } satisfies FakeAPIKey;
+ },
  };
 
  return self;

integration/tests/machine-auth/api-keys.test.ts

@@ -0,0 +1,214 @@
+import type { User } from '@clerk/backend';
+import { TokenType } from '@clerk/backend/internal';
+import { expect, test } from '@playwright/test';
+
+import type { Application } from '../../models/application';
+import { appConfigs } from '../../presets';
+import type { FakeAPIKey, FakeUser } from '../../testUtils';
+import { createTestUtils } from '../../testUtils';
+
+test.describe('Next.js API key auth within clerkMiddleware() @nextjs', () => {
+ test.describe.configure({ mode: 'parallel' });
+ let app: Application;
+ let fakeUser: FakeUser;
+ let fakeBapiUser: User;
+ let fakeAPIKey: FakeAPIKey;
+
+ test.beforeAll(async () => {
+ app = await appConfigs.next.appRouter
+ .clone()
+ .addFile(
+ `src/middleware.ts`,
+ () => `
+ import { clerkMiddleware, createRouteMatcher } from '@clerk/nextjs/server';
+
+ const isProtectedRoute = createRouteMatcher(['/api(.*)']);
+
+ export default clerkMiddleware(async (auth, req) => {
+ if (isProtectedRoute(req)) {
+ await auth.protect({ token: 'api_key' });
+ }
+ });
+
+ export const config = {
+ matcher: [
+ '/((?!.*\\..*|_next).*)', // Don't run middleware on static files
+ '/', // Run middleware on index page
+ '/(api|trpc)(.*)',
+ ], // Run middleware on API routes
+ };
+ `,
+ )
+ .addFile(
+ 'src/app/api/me/route.ts',
+ () => `
+ import { auth } from '@clerk/nextjs/server';
+
+ export async function GET() {
+ const { userId, tokenType } = await auth({ acceptsToken: 'api_key' });
+
+ return Response.json({ userId, tokenType });
+ }
+ `,
+ )
+ .commit();
+
+ await app.setup();
+ await app.withEnv(appConfigs.envs.withAPIKeys);
+ await app.dev();
+
+ const u = createTestUtils({ app });
+ fakeUser = u.services.users.createFakeUser();
+ fakeBapiUser = await u.services.users.createBapiUser(fakeUser);
+ fakeAPIKey = await u.services.users.createFakeAPIKey(fakeBapiUser.id);
+ });
+
+ test.afterAll(async () => {
+ await fakeAPIKey.revoke();
+ await fakeUser.deleteIfExists();
+ await app.teardown();
+ });
+
+ test('should return 401 if no API key is provided', async ({ request }) => {
+ const url = new URL('/api/me', app.serverUrl);
+ const res = await request.get(url.toString());
+ expect(res.status()).toBe(401);
+ });
+
+ test('should return 401 if API key is invalid', async ({ request }) => {
+ const url = new URL('/api/me', app.serverUrl);
+ const res = await request.get(url.toString(), {
+ headers: { Authorization: 'Bearer invalid_key' },
+ });
+ expect(res.status()).toBe(401);
+ });
+
+ test('should return 200 with auth object if API key is valid', async ({ request }) => {
+ const url = new URL('/api/me', app.serverUrl);
+ const res = await request.get(url.toString(), {
+ headers: {
+ Authorization: `Bearer ${fakeAPIKey.secret}`,
+ },
+ });
+ const apiKeyData = await res.json();
+ expect(res.status()).toBe(200);
+ expect(apiKeyData.userId).toBe(fakeBapiUser.id);
+ expect(apiKeyData.tokenType).toBe(TokenType.ApiKey);
+ });
+});
+
+test.describe('Next.js API key auth within routes @nextjs', () => {
+ test.describe.configure({ mode: 'parallel' });
+ let app: Application;
+ let fakeUser: FakeUser;
+ let fakeBapiUser: User;
+ let fakeAPIKey: FakeAPIKey;
+
+ test.beforeAll(async () => {
+ app = await appConfigs.next.appRouter
+ .clone()
+ .addFile(
+ 'src/app/api/me/route.ts',
+ () => `
+ import { auth } from '@clerk/nextjs/server';
+
+ export async function GET() {
+ const { userId, tokenType } = await auth({ acceptsToken: 'api_key' });
+
+ if (!userId) {
+ return Response.json({ error: 'Unauthorized' }, { status: 401 });
+ }
+
+ return Response.json({ userId, tokenType });
+ }
+
+ export async function POST() {
+ const authObject = await auth({ acceptsToken: ['api_key', 'session_token'] });
+
+ if (!authObject.isAuthenticated) {
+ return Response.json({ error: 'Unauthorized' }, { status: 401 });
+ }
+
+ return Response.json({ userId: authObject.userId, tokenType: authObject.tokenType });
+ }
+ `,
+ )
+ .commit();
+
+ await app.setup();
+ await app.withEnv(appConfigs.envs.withAPIKeys);
+ await app.dev();
+
+ const u = createTestUtils({ app });
+ fakeUser = u.services.users.createFakeUser();
+ fakeBapiUser = await u.services.users.createBapiUser(fakeUser);
+ fakeAPIKey = await u.services.users.createFakeAPIKey(fakeBapiUser.id);
+ });
+
+ test.afterAll(async () => {
+ await fakeAPIKey.revoke();
+ await fakeUser.deleteIfExists();
+ await app.teardown();
+ });
+
+ test('should return 401 if no API key is provided', async ({ request }) => {
+ const url = new URL('/api/me', app.serverUrl);
+ const res = await request.get(url.toString());
+ expect(res.status()).toBe(401);
+ });
+
+ test('should return 401 if API key is invalid', async ({ request }) => {
+ const url = new URL('/api/me', app.serverUrl);
+ const res = await request.get(url.toString(), {
+ headers: { Authorization: 'Bearer invalid_key' },
+ });
+ expect(res.status()).toBe(401);
+ });
+
+ test('should return 200 with auth object if API key is valid', async ({ request }) => {
+ const url = new URL('/api/me', app.serverUrl);
+ const res = await request.get(url.toString(), {
+ headers: {
+ Authorization: `Bearer ${fakeAPIKey.secret}`,
+ },
+ });
+ const apiKeyData = await res.json();
+ expect(res.status()).toBe(200);
+ expect(apiKeyData.userId).toBe(fakeBapiUser.id);
+ expect(apiKeyData.tokenType).toBe(TokenType.ApiKey);
+ });
+
+ test('should handle multiple token types', async ({ page, context }) => {
+ const u = createTestUtils({ app, page, context });
+ const url = new URL('/api/me', app.serverUrl);
+
+ // Sign in to get a session token
+ await u.po.signIn.goTo();
+ await u.po.signIn.waitForMounted();
+ await u.po.signIn.signInWithEmailAndInstantPassword({ email: fakeUser.email, password: fakeUser.password });
+ await u.po.expect.toBeSignedIn();
+
+ // GET endpoint (only accepts api_key)
+ const getRes = await u.page.request.get(url.toString());
+ expect(getRes.status()).toBe(401);
+
+ // POST endpoint (accepts both api_key and session_token)
+ // Test with session token
+ const postWithSessionRes = await u.page.request.post(url.toString());
+ const sessionData = await postWithSessionRes.json();
+ expect(postWithSessionRes.status()).toBe(200);
+ expect(sessionData.userId).toBe(fakeBapiUser.id);
+ expect(sessionData.tokenType).toBe(TokenType.SessionToken);
+
+ // Test with API key
+ const postWithApiKeyRes = await u.page.request.post(url.toString(), {
+ headers: {
+ Authorization: `Bearer ${fakeAPIKey.secret}`,
+ },
+ });
+ const apiKeyData = await postWithApiKeyRes.json();
+ expect(postWithApiKeyRes.status()).toBe(200);
+ expect(apiKeyData.userId).toBe(fakeBapiUser.id);
+ expect(apiKeyData.tokenType).toBe(TokenType.ApiKey);
+ });
+});

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

@@ -4,7 +4,67 @@ import { AbstractAPI } from './AbstractApi';
 
 const basePath = '/api_keys';
 
+type CreateAPIKeyParams = {
+ type?: 'api_key';
+ /**
+ * API key name
+ */
+ name: string;
+ /**
+ * user or organization ID the API key is associated with
+ */
+ subject: string;
+ /**
+ * API key description
+ */
+ description?: string | null;
+ claims?: Record<string, any> | null;
+ scopes?: string[];
+ createdBy?: string | null;
+ secondsUntilExpiration?: number | null;
+};
+
+type RevokeAPIKeyParams = {
+ /**
+ * API key ID
+ */
+ apiKeyId: string;
+ /**
+ * Reason for revocation
+ */
+ revocationReason?: string | null;
+};
+
 export class APIKeysAPI extends AbstractAPI {
+ async create(params: CreateAPIKeyParams) {
+ return this.request<APIKey>({
+ method: 'POST',
+ path: basePath,
+ bodyParams: params,
+ });
+ }
+
+ async revoke(params: RevokeAPIKeyParams) {
+ const { apiKeyId, ...bodyParams } = params;
+
+ this.requireId(apiKeyId);
+
+ return this.request<APIKey>({
+ method: 'POST',
+ path: joinPaths(basePath, apiKeyId, 'revoke'),
+ bodyParams,
+ });
+ }
+
+ async getSecret(apiKeyId: string) {
+ this.requireId(apiKeyId);
+
+ return this.request<{ secret: string }>({
+ method: 'GET',
+ path: joinPaths(basePath, apiKeyId, 'secret'),
+ });
+ }
+
  async verifySecret(secret: string) {
  return this.request<APIKey>({
  method: 'POST',

.changeset/eighty-frogs-return.md

@@ -0,0 +1,5 @@
+---
+"@clerk/nextjs": minor
+---
+
+Fix `auth.protect()` unauthorized error propagation within middleware

.changeset/weak-adults-clean.md

@@ -0,0 +1,5 @@
+---
+"@clerk/backend": minor
+---
+
+Introduce API keys Backend SDK methods

integration/.keys.json.sample

@@ -54,5 +54,9 @@
  "with-whatsapp-phone-code": {
  "pk": "",
  "sk": ""
+ },
+ "with-api-keys": {
+ "pk": "",
+ "sk": ""
  }
 }

integration/presets/envs.ts

@@ -163,6 +163,12 @@ const withWhatsappPhoneCode = base
  .setEnvVariable('private', 'CLERK_SECRET_KEY', instanceKeys.get('with-whatsapp-phone-code').sk)
  .setEnvVariable('public', 'CLERK_PUBLISHABLE_KEY', instanceKeys.get('with-whatsapp-phone-code').pk);
 
+const withAPIKeys = base
+ .clone()
+ .setId('withAPIKeys')
+ .setEnvVariable('private', 'CLERK_SECRET_KEY', instanceKeys.get('with-api-keys').sk)
+ .setEnvVariable('public', 'CLERK_PUBLISHABLE_KEY', instanceKeys.get('with-api-keys').pk);
+
 export const envs = {
  base,
  withKeyless,
@@ -187,4 +193,5 @@ export const envs = {
  withBillingStaging,
  withBilling,
  withWhatsappPhoneCode,
+ withAPIKeys,
 } as const;

integration/presets/longRunningApps.ts

@@ -42,6 +42,7 @@ export const createLongRunningApps = () => {
  config: next.appRouter,
  env: envs.withSessionTasks,
  },
+ { id: 'next.appRouter.withAPIKeys', config: next.appRouter, env: envs.withAPIKeys },
  { id: 'withBillingStaging.next.appRouter', config: next.appRouter, env: envs.withBillingStaging },
  { id: 'withBilling.next.appRouter', config: next.appRouter, env: envs.withBilling },
  { id: 'withBillingStaging.vue.vite', config: vue.vite, env: envs.withBillingStaging },

integration/testUtils/index.ts

@@ -6,10 +6,10 @@ import type { Application } from '../models/application';
 import { createEmailService } from './emailService';
 import { createInvitationService } from './invitationsService';
 import { createOrganizationsService } from './organizationsService';
-import type { FakeOrganization, FakeUser } from './usersService';
+import type { FakeAPIKey, FakeOrganization, FakeUser } from './usersService';
 import { createUserService } from './usersService';
 
-export type { FakeUser, FakeOrganization };
+export type { FakeUser, FakeOrganization, FakeAPIKey };
 const createClerkClient = (app: Application) => {
  return backendCreateClerkClient({
  apiUrl: app.env.privateVariables.get('CLERK_API_URL'),

integration/testUtils/usersService.ts

@@ -1,4 +1,4 @@
-import type { ClerkClient, Organization, User } from '@clerk/backend';
+import type { APIKey, ClerkClient, Organization, User } from '@clerk/backend';
 import { faker } from '@faker-js/faker';
 
 import { hash } from '../models/helpers';
@@ -57,6 +57,12 @@ export type FakeOrganization = {
  delete: () => Promise<Organization>;
 };
 
+export type FakeAPIKey = {
+ apiKey: APIKey;
+ secret: string;
+ revoke: () => Promise<APIKey>;
+};
+
 export type UserService = {
  createFakeUser: (options?: FakeUserOptions) => FakeUser;
  createBapiUser: (fakeUser: FakeUser) => Promise<User>;
@@ -67,6 +73,7 @@ export type UserService = {
  deleteIfExists: (opts: { id?: string; email?: string; phoneNumber?: string }) => Promise<void>;
  createFakeOrganization: (userId: string) => Promise<FakeOrganization>;
  getUser: (opts: { id?: string; email?: string }) => Promise<User | undefined>;
+ createFakeAPIKey: (userId: string) => Promise<FakeAPIKey>;
 };
 
 /**
@@ -175,6 +182,23 @@ export const createUserService = (clerkClient: ClerkClient) => {
  delete: () => clerkClient.organizations.deleteOrganization(organization.id),
  } satisfies FakeOrganization;
  },
+ createFakeAPIKey: async (userId: string) => {
+ const TWENTY_MINUTES = 20 * 60;
+
+ const apiKey = await clerkClient.apiKeys.create({
+ subject: userId,
+ name: `Integration Test - ${userId}`,
+ secondsUntilExpiration: TWENTY_MINUTES,
+ });
+
+ const { secret } = await clerkClient.apiKeys.getSecret(apiKey.id);
+
+ return {
+ apiKey,
+ secret,
+ revoke: () => clerkClient.apiKeys.revoke({ apiKeyId: apiKey.id, revocationReason: 'For testing purposes' }),
+ } satisfies FakeAPIKey;
+ },
  };
 
  return self;

integration/tests/machine-auth/api-keys.test.ts

@@ -0,0 +1,214 @@
+import type { User } from '@clerk/backend';
+import { TokenType } from '@clerk/backend/internal';
+import { expect, test } from '@playwright/test';
+
+import type { Application } from '../../models/application';
+import { appConfigs } from '../../presets';
+import type { FakeAPIKey, FakeUser } from '../../testUtils';
+import { createTestUtils } from '../../testUtils';
+
+test.describe('Next.js API key auth within clerkMiddleware() @nextjs', () => {
+ test.describe.configure({ mode: 'parallel' });
+ let app: Application;
+ let fakeUser: FakeUser;
+ let fakeBapiUser: User;
+ let fakeAPIKey: FakeAPIKey;
+
+ test.beforeAll(async () => {
+ app = await appConfigs.next.appRouter
+ .clone()
+ .addFile(
+ `src/middleware.ts`,
+ () => `
+ import { clerkMiddleware, createRouteMatcher } from '@clerk/nextjs/server';
+
+ const isProtectedRoute = createRouteMatcher(['/api(.*)']);
+
+ export default clerkMiddleware(async (auth, req) => {
+ if (isProtectedRoute(req)) {
+ await auth.protect({ token: 'api_key' });
+ }
+ });
+
+ export const config = {
+ matcher: [
+ '/((?!.*\\..*|_next).*)', // Don't run middleware on static files
+ '/', // Run middleware on index page
+ '/(api|trpc)(.*)',
+ ], // Run middleware on API routes
+ };
+ `,
+ )
+ .addFile(
+ 'src/app/api/me/route.ts',
+ () => `
+ import { auth } from '@clerk/nextjs/server';
+
+ export async function GET() {
+ const { userId, tokenType } = await auth({ acceptsToken: 'api_key' });
+
+ return Response.json({ userId, tokenType });
+ }
+ `,
+ )
+ .commit();
+
+ await app.setup();
+ await app.withEnv(appConfigs.envs.withAPIKeys);
+ await app.dev();
+
+ const u = createTestUtils({ app });
+ fakeUser = u.services.users.createFakeUser();
+ fakeBapiUser = await u.services.users.createBapiUser(fakeUser);
+ fakeAPIKey = await u.services.users.createFakeAPIKey(fakeBapiUser.id);
+ });
+
+ test.afterAll(async () => {
+ await fakeAPIKey.revoke();
+ await fakeUser.deleteIfExists();
+ await app.teardown();
+ });
+
+ test('should return 401 if no API key is provided', async ({ request }) => {
+ const url = new URL('/api/me', app.serverUrl);
+ const res = await request.get(url.toString());
+ expect(res.status()).toBe(401);
+ });
+
+ test('should return 401 if API key is invalid', async ({ request }) => {
+ const url = new URL('/api/me', app.serverUrl);
+ const res = await request.get(url.toString(), {
+ headers: { Authorization: 'Bearer invalid_key' },
+ });
+ expect(res.status()).toBe(401);
+ });
+
+ test('should return 200 with auth object if API key is valid', async ({ request }) => {
+ const url = new URL('/api/me', app.serverUrl);
+ const res = await request.get(url.toString(), {
+ headers: {
+ Authorization: `Bearer ${fakeAPIKey.secret}`,
+ },
+ });
+ const apiKeyData = await res.json();
+ expect(res.status()).toBe(200);
+ expect(apiKeyData.userId).toBe(fakeBapiUser.id);
+ expect(apiKeyData.tokenType).toBe(TokenType.ApiKey);
+ });
+});
+
+test.describe('Next.js API key auth within routes @nextjs', () => {
+ test.describe.configure({ mode: 'parallel' });
+ let app: Application;
+ let fakeUser: FakeUser;
+ let fakeBapiUser: User;
+ let fakeAPIKey: FakeAPIKey;
+
+ test.beforeAll(async () => {
+ app = await appConfigs.next.appRouter
+ .clone()
+ .addFile(
+ 'src/app/api/me/route.ts',
+ () => `
+ import { auth } from '@clerk/nextjs/server';
+
+ export async function GET() {
+ const { userId, tokenType } = await auth({ acceptsToken: 'api_key' });
+
+ if (!userId) {
+ return Response.json({ error: 'Unauthorized' }, { status: 401 });
+ }
+
+ return Response.json({ userId, tokenType });
+ }
+
+ export async function POST() {
+ const authObject = await auth({ acceptsToken: ['api_key', 'session_token'] });
+
+ if (!authObject.isAuthenticated) {
+ return Response.json({ error: 'Unauthorized' }, { status: 401 });
+ }
+
+ return Response.json({ userId: authObject.userId, tokenType: authObject.tokenType });
+ }
+ `,
+ )
+ .commit();
+
+ await app.setup();
+ await app.withEnv(appConfigs.envs.withAPIKeys);
+ await app.dev();
+
+ const u = createTestUtils({ app });
+ fakeUser = u.services.users.createFakeUser();
+ fakeBapiUser = await u.services.users.createBapiUser(fakeUser);
+ fakeAPIKey = await u.services.users.createFakeAPIKey(fakeBapiUser.id);
+ });
+
+ test.afterAll(async () => {
+ await fakeAPIKey.revoke();
+ await fakeUser.deleteIfExists();
+ await app.teardown();
+ });
+
+ test('should return 401 if no API key is provided', async ({ request }) => {
+ const url = new URL('/api/me', app.serverUrl);
+ const res = await request.get(url.toString());
+ expect(res.status()).toBe(401);
+ });
+
+ test('should return 401 if API key is invalid', async ({ request }) => {
+ const url = new URL('/api/me', app.serverUrl);
+ const res = await request.get(url.toString(), {
+ headers: { Authorization: 'Bearer invalid_key' },
+ });
+ expect(res.status()).toBe(401);
+ });
+
+ test('should return 200 with auth object if API key is valid', async ({ request }) => {
+ const url = new URL('/api/me', app.serverUrl);
+ const res = await request.get(url.toString(), {
+ headers: {
+ Authorization: `Bearer ${fakeAPIKey.secret}`,
+ },
+ });
+ const apiKeyData = await res.json();
+ expect(res.status()).toBe(200);
+ expect(apiKeyData.userId).toBe(fakeBapiUser.id);
+ expect(apiKeyData.tokenType).toBe(TokenType.ApiKey);
+ });
+
+ test('should handle multiple token types', async ({ page, context }) => {
+ const u = createTestUtils({ app, page, context });
+ const url = new URL('/api/me', app.serverUrl);
+
+ // Sign in to get a session token
+ await u.po.signIn.goTo();
+ await u.po.signIn.waitForMounted();
+ await u.po.signIn.signInWithEmailAndInstantPassword({ email: fakeUser.email, password: fakeUser.password });
+ await u.po.expect.toBeSignedIn();
+
+ // GET endpoint (only accepts api_key)
+ const getRes = await u.page.request.get(url.toString());
+ expect(getRes.status()).toBe(401);
+
+ // POST endpoint (accepts both api_key and session_token)
+ // Test with session token
+ const postWithSessionRes = await u.page.request.post(url.toString());
+ const sessionData = await postWithSessionRes.json();
+ expect(postWithSessionRes.status()).toBe(200);
+ expect(sessionData.userId).toBe(fakeBapiUser.id);
+ expect(sessionData.tokenType).toBe(TokenType.SessionToken);
+
+ // Test with API key
+ const postWithApiKeyRes = await u.page.request.post(url.toString(), {
+ headers: {
+ Authorization: `Bearer ${fakeAPIKey.secret}`,
+ },
+ });
+ const apiKeyData = await postWithApiKeyRes.json();
+ expect(postWithApiKeyRes.status()).toBe(200);
+ expect(apiKeyData.userId).toBe(fakeBapiUser.id);
+ expect(apiKeyData.tokenType).toBe(TokenType.ApiKey);
+ });
+});

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

@@ -4,7 +4,67 @@ import { AbstractAPI } from './AbstractApi';
 
 const basePath = '/api_keys';
 
+type CreateAPIKeyParams = {
+ type?: 'api_key';
+ /**
+ * API key name
+ */
+ name: string;
+ /**
+ * user or organization ID the API key is associated with
+ */
+ subject: string;
+ /**
+ * API key description
+ */
+ description?: string | null;
+ claims?: Record<string, any> | null;
+ scopes?: string[];
+ createdBy?: string | null;
+ secondsUntilExpiration?: number | null;
+};
+
+type RevokeAPIKeyParams = {
+ /**
+ * API key ID
+ */
+ apiKeyId: string;
+ /**
+ * Reason for revocation
+ */
+ revocationReason?: string | null;
+};
+
 export class APIKeysAPI extends AbstractAPI {
+ async create(params: CreateAPIKeyParams) {
+ return this.request<APIKey>({
+ method: 'POST',
+ path: basePath,
+ bodyParams: params,
+ });
+ }
+
+ async revoke(params: RevokeAPIKeyParams) {
+ const { apiKeyId, ...bodyParams } = params;
+
+ this.requireId(apiKeyId);
+
+ return this.request<APIKey>({
+ method: 'POST',
+ path: joinPaths(basePath, apiKeyId, 'revoke'),
+ bodyParams,
+ });
+ }
+
+ async getSecret(apiKeyId: string) {
+ this.requireId(apiKeyId);
+
+ return this.request<{ secret: string }>({
+ method: 'GET',
+ path: joinPaths(basePath, apiKeyId, 'secret'),
+ });
+ }
+
  async verifySecret(secret: string) {
  return this.request<APIKey>({
  method: 'POST',

.changeset/eighty-frogs-return.md

@@ -0,0 +1,5 @@
+---
+"@clerk/nextjs": minor
+---
+
+Fix `auth.protect()` unauthorized error propagation within middleware

.changeset/weak-adults-clean.md

@@ -0,0 +1,5 @@
+---
+"@clerk/backend": minor
+---
+
+Introduce API keys Backend SDK methods

integration/.keys.json.sample

@@ -54,5 +54,9 @@
  "with-whatsapp-phone-code": {
  "pk": "",
  "sk": ""
+ },
+ "with-api-keys": {
+ "pk": "",
+ "sk": ""
  }
 }

integration/presets/envs.ts

@@ -163,6 +163,12 @@ const withWhatsappPhoneCode = base
  .setEnvVariable('private', 'CLERK_SECRET_KEY', instanceKeys.get('with-whatsapp-phone-code').sk)
  .setEnvVariable('public', 'CLERK_PUBLISHABLE_KEY', instanceKeys.get('with-whatsapp-phone-code').pk);
 
+const withAPIKeys = base
+ .clone()
+ .setId('withAPIKeys')
+ .setEnvVariable('private', 'CLERK_SECRET_KEY', instanceKeys.get('with-api-keys').sk)
+ .setEnvVariable('public', 'CLERK_PUBLISHABLE_KEY', instanceKeys.get('with-api-keys').pk);
+
 export const envs = {
  base,
  withKeyless,
@@ -187,4 +193,5 @@ export const envs = {
  withBillingStaging,
  withBilling,
  withWhatsappPhoneCode,
+ withAPIKeys,
 } as const;

integration/presets/longRunningApps.ts

@@ -42,6 +42,7 @@ export const createLongRunningApps = () => {
  config: next.appRouter,
  env: envs.withSessionTasks,
  },
+ { id: 'next.appRouter.withAPIKeys', config: next.appRouter, env: envs.withAPIKeys },
  { id: 'withBillingStaging.next.appRouter', config: next.appRouter, env: envs.withBillingStaging },
  { id: 'withBilling.next.appRouter', config: next.appRouter, env: envs.withBilling },
  { id: 'withBillingStaging.vue.vite', config: vue.vite, env: envs.withBillingStaging },

integration/testUtils/index.ts

@@ -6,10 +6,10 @@ import type { Application } from '../models/application';
 import { createEmailService } from './emailService';
 import { createInvitationService } from './invitationsService';
 import { createOrganizationsService } from './organizationsService';
-import type { FakeOrganization, FakeUser } from './usersService';
+import type { FakeAPIKey, FakeOrganization, FakeUser } from './usersService';
 import { createUserService } from './usersService';
 
-export type { FakeUser, FakeOrganization };
+export type { FakeUser, FakeOrganization, FakeAPIKey };
 const createClerkClient = (app: Application) => {
  return backendCreateClerkClient({
  apiUrl: app.env.privateVariables.get('CLERK_API_URL'),

integration/testUtils/usersService.ts

@@ -1,4 +1,4 @@
-import type { ClerkClient, Organization, User } from '@clerk/backend';
+import type { APIKey, ClerkClient, Organization, User } from '@clerk/backend';
 import { faker } from '@faker-js/faker';
 
 import { hash } from '../models/helpers';
@@ -57,6 +57,12 @@ export type FakeOrganization = {
  delete: () => Promise<Organization>;
 };
 
+export type FakeAPIKey = {
+ apiKey: APIKey;
+ secret: string;
+ revoke: () => Promise<APIKey>;
+};
+
 export type UserService = {
  createFakeUser: (options?: FakeUserOptions) => FakeUser;
  createBapiUser: (fakeUser: FakeUser) => Promise<User>;
@@ -67,6 +73,7 @@ export type UserService = {
  deleteIfExists: (opts: { id?: string; email?: string; phoneNumber?: string }) => Promise<void>;
  createFakeOrganization: (userId: string) => Promise<FakeOrganization>;
  getUser: (opts: { id?: string; email?: string }) => Promise<User | undefined>;
+ createFakeAPIKey: (userId: string) => Promise<FakeAPIKey>;
 };
 
 /**
@@ -175,6 +182,23 @@ export const createUserService = (clerkClient: ClerkClient) => {
  delete: () => clerkClient.organizations.deleteOrganization(organization.id),
  } satisfies FakeOrganization;
  },
+ createFakeAPIKey: async (userId: string) => {
+ const TWENTY_MINUTES = 20 * 60;
+
+ const apiKey = await clerkClient.apiKeys.create({
+ subject: userId,
+ name: `Integration Test - ${userId}`,
+ secondsUntilExpiration: TWENTY_MINUTES,
+ });
+
+ const { secret } = await clerkClient.apiKeys.getSecret(apiKey.id);
+
+ return {
+ apiKey,
+ secret,
+ revoke: () => clerkClient.apiKeys.revoke({ apiKeyId: apiKey.id, revocationReason: 'For testing purposes' }),
+ } satisfies FakeAPIKey;
+ },
  };
 
  return self;

integration/tests/machine-auth/api-keys.test.ts

@@ -0,0 +1,214 @@
+import type { User } from '@clerk/backend';
+import { TokenType } from '@clerk/backend/internal';
+import { expect, test } from '@playwright/test';
+
+import type { Application } from '../../models/application';
+import { appConfigs } from '../../presets';
+import type { FakeAPIKey, FakeUser } from '../../testUtils';
+import { createTestUtils } from '../../testUtils';
+
+test.describe('Next.js API key auth within clerkMiddleware() @nextjs', () => {
+ test.describe.configure({ mode: 'parallel' });
+ let app: Application;
+ let fakeUser: FakeUser;
+ let fakeBapiUser: User;
+ let fakeAPIKey: FakeAPIKey;
+
+ test.beforeAll(async () => {
+ app = await appConfigs.next.appRouter
+ .clone()
+ .addFile(
+ `src/middleware.ts`,
+ () => `
+ import { clerkMiddleware, createRouteMatcher } from '@clerk/nextjs/server';
+
+ const isProtectedRoute = createRouteMatcher(['/api(.*)']);
+
+ export default clerkMiddleware(async (auth, req) => {
+ if (isProtectedRoute(req)) {
+ await auth.protect({ token: 'api_key' });
+ }
+ });
+
+ export const config = {
+ matcher: [
+ '/((?!.*\\..*|_next).*)', // Don't run middleware on static files
+ '/', // Run middleware on index page
+ '/(api|trpc)(.*)',
+ ], // Run middleware on API routes
+ };
+ `,
+ )
+ .addFile(
+ 'src/app/api/me/route.ts',
+ () => `
+ import { auth } from '@clerk/nextjs/server';
+
+ export async function GET() {
+ const { userId, tokenType } = await auth({ acceptsToken: 'api_key' });
+
+ return Response.json({ userId, tokenType });
+ }
+ `,
+ )
+ .commit();
+
+ await app.setup();
+ await app.withEnv(appConfigs.envs.withAPIKeys);
+ await app.dev();
+
+ const u = createTestUtils({ app });
+ fakeUser = u.services.users.createFakeUser();
+ fakeBapiUser = await u.services.users.createBapiUser(fakeUser);
+ fakeAPIKey = await u.services.users.createFakeAPIKey(fakeBapiUser.id);
+ });
+
+ test.afterAll(async () => {
+ await fakeAPIKey.revoke();
+ await fakeUser.deleteIfExists();
+ await app.teardown();
+ });
+
+ test('should return 401 if no API key is provided', async ({ request }) => {
+ const url = new URL('/api/me', app.serverUrl);
+ const res = await request.get(url.toString());
+ expect(res.status()).toBe(401);
+ });
+
+ test('should return 401 if API key is invalid', async ({ request }) => {
+ const url = new URL('/api/me', app.serverUrl);
+ const res = await request.get(url.toString(), {
+ headers: { Authorization: 'Bearer invalid_key' },
+ });
+ expect(res.status()).toBe(401);
+ });
+
+ test('should return 200 with auth object if API key is valid', async ({ request }) => {
+ const url = new URL('/api/me', app.serverUrl);
+ const res = await request.get(url.toString(), {
+ headers: {
+ Authorization: `Bearer ${fakeAPIKey.secret}`,
+ },
+ });
+ const apiKeyData = await res.json();
+ expect(res.status()).toBe(200);
+ expect(apiKeyData.userId).toBe(fakeBapiUser.id);
+ expect(apiKeyData.tokenType).toBe(TokenType.ApiKey);
+ });
+});
+
+test.describe('Next.js API key auth within routes @nextjs', () => {
+ test.describe.configure({ mode: 'parallel' });
+ let app: Application;
+ let fakeUser: FakeUser;
+ let fakeBapiUser: User;
+ let fakeAPIKey: FakeAPIKey;
+
+ test.beforeAll(async () => {
+ app = await appConfigs.next.appRouter
+ .clone()
+ .addFile(
+ 'src/app/api/me/route.ts',
+ () => `
+ import { auth } from '@clerk/nextjs/server';
+
+ export async function GET() {
+ const { userId, tokenType } = await auth({ acceptsToken: 'api_key' });
+
+ if (!userId) {
+ return Response.json({ error: 'Unauthorized' }, { status: 401 });
+ }
+
+ return Response.json({ userId, tokenType });
+ }
+
+ export async function POST() {
+ const authObject = await auth({ acceptsToken: ['api_key', 'session_token'] });
+
+ if (!authObject.isAuthenticated) {
+ return Response.json({ error: 'Unauthorized' }, { status: 401 });
+ }
+
+ return Response.json({ userId: authObject.userId, tokenType: authObject.tokenType });
+ }
+ `,
+ )
+ .commit();
+
+ await app.setup();
+ await app.withEnv(appConfigs.envs.withAPIKeys);
+ await app.dev();
+
+ const u = createTestUtils({ app });
+ fakeUser = u.services.users.createFakeUser();
+ fakeBapiUser = await u.services.users.createBapiUser(fakeUser);
+ fakeAPIKey = await u.services.users.createFakeAPIKey(fakeBapiUser.id);
+ });
+
+ test.afterAll(async () => {
+ await fakeAPIKey.revoke();
+ await fakeUser.deleteIfExists();
+ await app.teardown();
+ });
+
+ test('should return 401 if no API key is provided', async ({ request }) => {
+ const url = new URL('/api/me', app.serverUrl);
+ const res = await request.get(url.toString());
+ expect(res.status()).toBe(401);
+ });
+
+ test('should return 401 if API key is invalid', async ({ request }) => {
+ const url = new URL('/api/me', app.serverUrl);
+ const res = await request.get(url.toString(), {
+ headers: { Authorization: 'Bearer invalid_key' },
+ });
+ expect(res.status()).toBe(401);
+ });
+
+ test('should return 200 with auth object if API key is valid', async ({ request }) => {
+ const url = new URL('/api/me', app.serverUrl);
+ const res = await request.get(url.toString(), {
+ headers: {
+ Authorization: `Bearer ${fakeAPIKey.secret}`,
+ },
+ });
+ const apiKeyData = await res.json();
+ expect(res.status()).toBe(200);
+ expect(apiKeyData.userId).toBe(fakeBapiUser.id);
+ expect(apiKeyData.tokenType).toBe(TokenType.ApiKey);
+ });
+
+ test('should handle multiple token types', async ({ page, context }) => {
+ const u = createTestUtils({ app, page, context });
+ const url = new URL('/api/me', app.serverUrl);
+
+ // Sign in to get a session token
+ await u.po.signIn.goTo();
+ await u.po.signIn.waitForMounted();
+ await u.po.signIn.signInWithEmailAndInstantPassword({ email: fakeUser.email, password: fakeUser.password });
+ await u.po.expect.toBeSignedIn();
+
+ // GET endpoint (only accepts api_key)
+ const getRes = await u.page.request.get(url.toString());
+ expect(getRes.status()).toBe(401);
+
+ // POST endpoint (accepts both api_key and session_token)
+ // Test with session token
+ const postWithSessionRes = await u.page.request.post(url.toString());
+ const sessionData = await postWithSessionRes.json();
+ expect(postWithSessionRes.status()).toBe(200);
+ expect(sessionData.userId).toBe(fakeBapiUser.id);
+ expect(sessionData.tokenType).toBe(TokenType.SessionToken);
+
+ // Test with API key
+ const postWithApiKeyRes = await u.page.request.post(url.toString(), {
+ headers: {
+ Authorization: `Bearer ${fakeAPIKey.secret}`,
+ },
+ });
+ const apiKeyData = await postWithApiKeyRes.json();
+ expect(postWithApiKeyRes.status()).toBe(200);
+ expect(apiKeyData.userId).toBe(fakeBapiUser.id);
+ expect(apiKeyData.tokenType).toBe(TokenType.ApiKey);
+ });
+});

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

@@ -4,7 +4,67 @@ import { AbstractAPI } from './AbstractApi';
 
 const basePath = '/api_keys';
 
+type CreateAPIKeyParams = {
+ type?: 'api_key';
+ /**
+ * API key name
+ */
+ name: string;
+ /**
+ * user or organization ID the API key is associated with
+ */
+ subject: string;
+ /**
+ * API key description
+ */
+ description?: string | null;
+ claims?: Record<string, any> | null;
+ scopes?: string[];
+ createdBy?: string | null;
+ secondsUntilExpiration?: number | null;
+};
+
+type RevokeAPIKeyParams = {
+ /**
+ * API key ID
+ */
+ apiKeyId: string;
+ /**
+ * Reason for revocation
+ */
+ revocationReason?: string | null;
+};
+
 export class APIKeysAPI extends AbstractAPI {
+ async create(params: CreateAPIKeyParams) {
+ return this.request<APIKey>({
+ method: 'POST',
+ path: basePath,
+ bodyParams: params,
+ });
+ }
+
+ async revoke(params: RevokeAPIKeyParams) {
+ const { apiKeyId, ...bodyParams } = params;
+
+ this.requireId(apiKeyId);
+
+ return this.request<APIKey>({
+ method: 'POST',
+ path: joinPaths(basePath, apiKeyId, 'revoke'),
+ bodyParams,
+ });
+ }
+
+ async getSecret(apiKeyId: string) {
+ this.requireId(apiKeyId);
+
+ return this.request<{ secret: string }>({
+ method: 'GET',
+ path: joinPaths(basePath, apiKeyId, 'secret'),
+ });
+ }
+
  async verifySecret(secret: string) {
  return this.request<APIKey>({
  method: 'POST',

.changeset/eighty-frogs-return.md

@@ -0,0 +1,5 @@
+---
+"@clerk/nextjs": minor
+---
+
+Fix `auth.protect()` unauthorized error propagation within middleware

.changeset/weak-adults-clean.md

@@ -0,0 +1,5 @@
+---
+"@clerk/backend": minor
+---
+
+Introduce API keys Backend SDK methods

integration/.keys.json.sample

@@ -54,5 +54,9 @@
  "with-whatsapp-phone-code": {
  "pk": "",
  "sk": ""
+ },
+ "with-api-keys": {
+ "pk": "",
+ "sk": ""
  }
 }

integration/presets/envs.ts

@@ -163,6 +163,12 @@ const withWhatsappPhoneCode = base
  .setEnvVariable('private', 'CLERK_SECRET_KEY', instanceKeys.get('with-whatsapp-phone-code').sk)
  .setEnvVariable('public', 'CLERK_PUBLISHABLE_KEY', instanceKeys.get('with-whatsapp-phone-code').pk);
 
+const withAPIKeys = base
+ .clone()
+ .setId('withAPIKeys')
+ .setEnvVariable('private', 'CLERK_SECRET_KEY', instanceKeys.get('with-api-keys').sk)
+ .setEnvVariable('public', 'CLERK_PUBLISHABLE_KEY', instanceKeys.get('with-api-keys').pk);
+
 export const envs = {
  base,
  withKeyless,
@@ -187,4 +193,5 @@ export const envs = {
  withBillingStaging,
  withBilling,
  withWhatsappPhoneCode,
+ withAPIKeys,
 } as const;

integration/presets/longRunningApps.ts

@@ -42,6 +42,7 @@ export const createLongRunningApps = () => {
  config: next.appRouter,
  env: envs.withSessionTasks,
  },
+ { id: 'next.appRouter.withAPIKeys', config: next.appRouter, env: envs.withAPIKeys },
  { id: 'withBillingStaging.next.appRouter', config: next.appRouter, env: envs.withBillingStaging },
  { id: 'withBilling.next.appRouter', config: next.appRouter, env: envs.withBilling },
  { id: 'withBillingStaging.vue.vite', config: vue.vite, env: envs.withBillingStaging },

integration/testUtils/index.ts

@@ -6,10 +6,10 @@ import type { Application } from '../models/application';
 import { createEmailService } from './emailService';
 import { createInvitationService } from './invitationsService';
 import { createOrganizationsService } from './organizationsService';
-import type { FakeOrganization, FakeUser } from './usersService';
+import type { FakeAPIKey, FakeOrganization, FakeUser } from './usersService';
 import { createUserService } from './usersService';
 
-export type { FakeUser, FakeOrganization };
+export type { FakeUser, FakeOrganization, FakeAPIKey };
 const createClerkClient = (app: Application) => {
  return backendCreateClerkClient({
  apiUrl: app.env.privateVariables.get('CLERK_API_URL'),

integration/testUtils/usersService.ts

@@ -1,4 +1,4 @@
-import type { ClerkClient, Organization, User } from '@clerk/backend';
+import type { APIKey, ClerkClient, Organization, User } from '@clerk/backend';
 import { faker } from '@faker-js/faker';
 
 import { hash } from '../models/helpers';
@@ -57,6 +57,12 @@ export type FakeOrganization = {
  delete: () => Promise<Organization>;
 };
 
+export type FakeAPIKey = {
+ apiKey: APIKey;
+ secret: string;
+ revoke: () => Promise<APIKey>;
+};
+
 export type UserService = {
  createFakeUser: (options?: FakeUserOptions) => FakeUser;
  createBapiUser: (fakeUser: FakeUser) => Promise<User>;
@@ -67,6 +73,7 @@ export type UserService = {
  deleteIfExists: (opts: { id?: string; email?: string; phoneNumber?: string }) => Promise<void>;
  createFakeOrganization: (userId: string) => Promise<FakeOrganization>;
  getUser: (opts: { id?: string; email?: string }) => Promise<User | undefined>;
+ createFakeAPIKey: (userId: string) => Promise<FakeAPIKey>;
 };
 
 /**
@@ -175,6 +182,23 @@ export const createUserService = (clerkClient: ClerkClient) => {
  delete: () => clerkClient.organizations.deleteOrganization(organization.id),
  } satisfies FakeOrganization;
  },
+ createFakeAPIKey: async (userId: string) => {
+ const TWENTY_MINUTES = 20 * 60;
+
+ const apiKey = await clerkClient.apiKeys.create({
+ subject: userId,
+ name: `Integration Test - ${userId}`,
+ secondsUntilExpiration: TWENTY_MINUTES,
+ });
+
+ const { secret } = await clerkClient.apiKeys.getSecret(apiKey.id);
+
+ return {
+ apiKey,
+ secret,
+ revoke: () => clerkClient.apiKeys.revoke({ apiKeyId: apiKey.id, revocationReason: 'For testing purposes' }),
+ } satisfies FakeAPIKey;
+ },
  };
 
  return self;

integration/tests/machine-auth/api-keys.test.ts

@@ -0,0 +1,214 @@
+import type { User } from '@clerk/backend';
+import { TokenType } from '@clerk/backend/internal';
+import { expect, test } from '@playwright/test';
+
+import type { Application } from '../../models/application';
+import { appConfigs } from '../../presets';
+import type { FakeAPIKey, FakeUser } from '../../testUtils';
+import { createTestUtils } from '../../testUtils';
+
+test.describe('Next.js API key auth within clerkMiddleware() @nextjs', () => {
+ test.describe.configure({ mode: 'parallel' });
+ let app: Application;
+ let fakeUser: FakeUser;
+ let fakeBapiUser: User;
+ let fakeAPIKey: FakeAPIKey;
+
+ test.beforeAll(async () => {
+ app = await appConfigs.next.appRouter
+ .clone()
+ .addFile(
+ `src/middleware.ts`,
+ () => `
+ import { clerkMiddleware, createRouteMatcher } from '@clerk/nextjs/server';
+
+ const isProtectedRoute = createRouteMatcher(['/api(.*)']);
+
+ export default clerkMiddleware(async (auth, req) => {
+ if (isProtectedRoute(req)) {
+ await auth.protect({ token: 'api_key' });
+ }
+ });
+
+ export const config = {
+ matcher: [
+ '/((?!.*\\..*|_next).*)', // Don't run middleware on static files
+ '/', // Run middleware on index page
+ '/(api|trpc)(.*)',
+ ], // Run middleware on API routes
+ };
+ `,
+ )
+ .addFile(
+ 'src/app/api/me/route.ts',
+ () => `
+ import { auth } from '@clerk/nextjs/server';
+
+ export async function GET() {
+ const { userId, tokenType } = await auth({ acceptsToken: 'api_key' });
+
+ return Response.json({ userId, tokenType });
+ }
+ `,
+ )
+ .commit();
+
+ await app.setup();
+ await app.withEnv(appConfigs.envs.withAPIKeys);
+ await app.dev();
+
+ const u = createTestUtils({ app });
+ fakeUser = u.services.users.createFakeUser();
+ fakeBapiUser = await u.services.users.createBapiUser(fakeUser);
+ fakeAPIKey = await u.services.users.createFakeAPIKey(fakeBapiUser.id);
+ });
+
+ test.afterAll(async () => {
+ await fakeAPIKey.revoke();
+ await fakeUser.deleteIfExists();
+ await app.teardown();
+ });
+
+ test('should return 401 if no API key is provided', async ({ request }) => {
+ const url = new URL('/api/me', app.serverUrl);
+ const res = await request.get(url.toString());
+ expect(res.status()).toBe(401);
+ });
+
+ test('should return 401 if API key is invalid', async ({ request }) => {
+ const url = new URL('/api/me', app.serverUrl);
+ const res = await request.get(url.toString(), {
+ headers: { Authorization: 'Bearer invalid_key' },
+ });
+ expect(res.status()).toBe(401);
+ });
+
+ test('should return 200 with auth object if API key is valid', async ({ request }) => {
+ const url = new URL('/api/me', app.serverUrl);
+ const res = await request.get(url.toString(), {
+ headers: {
+ Authorization: `Bearer ${fakeAPIKey.secret}`,
+ },
+ });
+ const apiKeyData = await res.json();
+ expect(res.status()).toBe(200);
+ expect(apiKeyData.userId).toBe(fakeBapiUser.id);
+ expect(apiKeyData.tokenType).toBe(TokenType.ApiKey);
+ });
+});
+
+test.describe('Next.js API key auth within routes @nextjs', () => {
+ test.describe.configure({ mode: 'parallel' });
+ let app: Application;
+ let fakeUser: FakeUser;
+ let fakeBapiUser: User;
+ let fakeAPIKey: FakeAPIKey;
+
+ test.beforeAll(async () => {
+ app = await appConfigs.next.appRouter
+ .clone()
+ .addFile(
+ 'src/app/api/me/route.ts',
+ () => `
+ import { auth } from '@clerk/nextjs/server';
+
+ export async function GET() {
+ const { userId, tokenType } = await auth({ acceptsToken: 'api_key' });
+
+ if (!userId) {
+ return Response.json({ error: 'Unauthorized' }, { status: 401 });
+ }
+
+ return Response.json({ userId, tokenType });
+ }
+
+ export async function POST() {
+ const authObject = await auth({ acceptsToken: ['api_key', 'session_token'] });
+
+ if (!authObject.isAuthenticated) {
+ return Response.json({ error: 'Unauthorized' }, { status: 401 });
+ }
+
+ return Response.json({ userId: authObject.userId, tokenType: authObject.tokenType });
+ }
+ `,
+ )
+ .commit();
+
+ await app.setup();
+ await app.withEnv(appConfigs.envs.withAPIKeys);
+ await app.dev();
+
+ const u = createTestUtils({ app });
+ fakeUser = u.services.users.createFakeUser();
+ fakeBapiUser = await u.services.users.createBapiUser(fakeUser);
+ fakeAPIKey = await u.services.users.createFakeAPIKey(fakeBapiUser.id);
+ });
+
+ test.afterAll(async () => {
+ await fakeAPIKey.revoke();
+ await fakeUser.deleteIfExists();
+ await app.teardown();
+ });
+
+ test('should return 401 if no API key is provided', async ({ request }) => {
+ const url = new URL('/api/me', app.serverUrl);
+ const res = await request.get(url.toString());
+ expect(res.status()).toBe(401);
+ });
+
+ test('should return 401 if API key is invalid', async ({ request }) => {
+ const url = new URL('/api/me', app.serverUrl);
+ const res = await request.get(url.toString(), {
+ headers: { Authorization: 'Bearer invalid_key' },
+ });
+ expect(res.status()).toBe(401);
+ });
+
+ test('should return 200 with auth object if API key is valid', async ({ request }) => {
+ const url = new URL('/api/me', app.serverUrl);
+ const res = await request.get(url.toString(), {
+ headers: {
+ Authorization: `Bearer ${fakeAPIKey.secret}`,
+ },
+ });
+ const apiKeyData = await res.json();
+ expect(res.status()).toBe(200);
+ expect(apiKeyData.userId).toBe(fakeBapiUser.id);
+ expect(apiKeyData.tokenType).toBe(TokenType.ApiKey);
+ });
+
+ test('should handle multiple token types', async ({ page, context }) => {
+ const u = createTestUtils({ app, page, context });
+ const url = new URL('/api/me', app.serverUrl);
+
+ // Sign in to get a session token
+ await u.po.signIn.goTo();
+ await u.po.signIn.waitForMounted();
+ await u.po.signIn.signInWithEmailAndInstantPassword({ email: fakeUser.email, password: fakeUser.password });
+ await u.po.expect.toBeSignedIn();
+
+ // GET endpoint (only accepts api_key)
+ const getRes = await u.page.request.get(url.toString());
+ expect(getRes.status()).toBe(401);
+
+ // POST endpoint (accepts both api_key and session_token)
+ // Test with session token
+ const postWithSessionRes = await u.page.request.post(url.toString());
+ const sessionData = await postWithSessionRes.json();
+ expect(postWithSessionRes.status()).toBe(200);
+ expect(sessionData.userId).toBe(fakeBapiUser.id);
+ expect(sessionData.tokenType).toBe(TokenType.SessionToken);
+
+ // Test with API key
+ const postWithApiKeyRes = await u.page.request.post(url.toString(), {
+ headers: {
+ Authorization: `Bearer ${fakeAPIKey.secret}`,
+ },
+ });
+ const apiKeyData = await postWithApiKeyRes.json();
+ expect(postWithApiKeyRes.status()).toBe(200);
+ expect(apiKeyData.userId).toBe(fakeBapiUser.id);
+ expect(apiKeyData.tokenType).toBe(TokenType.ApiKey);
+ });
+});

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

@@ -4,7 +4,67 @@ import { AbstractAPI } from './AbstractApi';
 
 const basePath = '/api_keys';
 
+type CreateAPIKeyParams = {
+ type?: 'api_key';
+ /**
+ * API key name
+ */
+ name: string;
+ /**
+ * user or organization ID the API key is associated with
+ */
+ subject: string;
+ /**
+ * API key description
+ */
+ description?: string | null;
+ claims?: Record<string, any> | null;
+ scopes?: string[];
+ createdBy?: string | null;
+ secondsUntilExpiration?: number | null;
+};
+
+type RevokeAPIKeyParams = {
+ /**
+ * API key ID
+ */
+ apiKeyId: string;
+ /**
+ * Reason for revocation
+ */
+ revocationReason?: string | null;
+};
+
 export class APIKeysAPI extends AbstractAPI {
+ async create(params: CreateAPIKeyParams) {
+ return this.request<APIKey>({
+ method: 'POST',
+ path: basePath,
+ bodyParams: params,
+ });
+ }
+
+ async revoke(params: RevokeAPIKeyParams) {
+ const { apiKeyId, ...bodyParams } = params;
+
+ this.requireId(apiKeyId);
+
+ return this.request<APIKey>({
+ method: 'POST',
+ path: joinPaths(basePath, apiKeyId, 'revoke'),
+ bodyParams,
+ });
+ }
+
+ async getSecret(apiKeyId: string) {
+ this.requireId(apiKeyId);
+
+ return this.request<{ secret: string }>({
+ method: 'GET',
+ path: joinPaths(basePath, apiKeyId, 'secret'),
+ });
+ }
+
  async verifySecret(secret: string) {
  return this.request<APIKey>({
  method: 'POST',