feat(clerk-js): Implement server-side pagination and filtering for API keys

.changeset/bright-papayas-accept.md

@@ -0,0 +1,6 @@
+---
+"@clerk/clerk-js": minor
+"@clerk/shared": minor
+---
+
+Implemented server-side pagination and filtering for API keys

integration/testUtils/usersService.ts

@@ -200,7 +200,7 @@ export const createUserService = (clerkClient: ClerkClient) => {
 
       const apiKey = await clerkClient.apiKeys.create({
         subject: userId,
-        name: `Integration Test - ${userId}`,
+        name: `Integration Test - ${faker.string.uuid()}`,
         secondsUntilExpiration: TWENTY_MINUTES,
       });
 

integration/tests/machine-auth/component.test.ts

@@ -66,6 +66,70 @@ testAgainstRunningApps({
     await expect(u.page.locator('.cl-apiKeysTable .cl-tableBody .cl-tableRow')).toHaveCount(2);
   });
 
+  test('pagination works correctly with multiple pages', async ({ page, context }) => {
+    const u = createTestUtils({ app, page, context });
+
+    // Create user and 6 API keys to trigger pagination (default perPage is 5)
+    const fakeUser = u.services.users.createFakeUser();
+    const bapiUser = await u.services.users.createBapiUser(fakeUser);
+    const fakeAPIKeys = await Promise.all(
+      Array.from({ length: 6 }, () => u.services.users.createFakeAPIKey(bapiUser.id)),
+    );
+
+    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();
+
+    await u.po.page.goToRelative('/api-keys');
+    await u.po.apiKeys.waitForMounted();
+
+    // Verify first page
+    await expect(u.page.getByText(/Displaying 1 – 5 of 6/i)).toBeVisible();
+    await expect(u.page.locator('.cl-apiKeysTable .cl-tableBody .cl-tableRow')).toHaveCount(5);
+
+    // Navigate to second page
+    const page2Button = u.page.locator('.cl-paginationButton').filter({ hasText: /^2$/ });
+    await page2Button.click();
+    await expect(u.page.getByText(/Displaying 6 – 6 of 6/i)).toBeVisible();
+    await expect(u.page.locator('.cl-apiKeysTable .cl-tableBody .cl-tableRow')).toHaveCount(1);
+
+    // Navigate back to first page
+    const page1Button = u.page.locator('.cl-paginationButton').filter({ hasText: /^1$/ });
+    await page1Button.click();
+    await expect(u.page.getByText(/Displaying 1 – 5 of 6/i)).toBeVisible();
+    await expect(u.page.locator('.cl-apiKeysTable .cl-tableBody .cl-tableRow')).toHaveCount(5);
+
+    // Cleanup
+    await Promise.all(fakeAPIKeys.map(key => key.revoke()));
+    await fakeUser.deleteIfExists();
+  });
+
+  test('pagination does not show when items fit in one page', async ({ page, context }) => {
+    const u = createTestUtils({ app, page, context });
+    await u.po.signIn.goTo();
+    await u.po.signIn.waitForMounted();
+    await u.po.signIn.signInWithEmailAndInstantPassword({ email: fakeAdmin.email, password: fakeAdmin.password });
+    await u.po.expect.toBeSignedIn();
+
+    await u.po.page.goToRelative('/api-keys');
+    await u.po.apiKeys.waitForMounted();
+
+    const apiKeyName = `${fakeAdmin.firstName}-single-page-${Date.now()}`;
+    await u.po.apiKeys.clickAddButton();
+    await u.po.apiKeys.waitForFormOpened();
+    await u.po.apiKeys.typeName(apiKeyName);
+    await u.po.apiKeys.selectExpiration('1d');
+    await u.po.apiKeys.clickSaveButton();
+
+    await u.po.apiKeys.waitForCopyModalOpened();
+    await u.po.apiKeys.clickCopyAndCloseButton();
+    await u.po.apiKeys.waitForCopyModalClosed();
+    await u.po.apiKeys.waitForFormClosed();
+
+    await expect(u.page.getByText(/Displaying.*of.*/i)).toBeHidden();
+  });
+
   test('can revoke api keys', async ({ page, context }) => {
     const u = createTestUtils({ app, page, context });
     await u.po.signIn.goTo();

packages/clerk-js/src/core/modules/apiKeys/index.ts

@@ -3,12 +3,14 @@ import type {
   ApiKeyJSON,
   APIKeyResource,
   APIKeysNamespace,
+  ClerkPaginatedResponse,
   CreateAPIKeyParams,
   GetAPIKeysParams,
   RevokeAPIKeyParams,
 } from '@clerk/shared/types';
 
 import type { FapiRequestInit } from '@/core/fapiClient';
+import { convertPageToOffsetSearchParams } from '@/utils/convertPageToOffsetSearchParams';
 
 import { APIKey, BaseResource } from '../../resources/internal';
 
@@ -35,23 +37,24 @@ export class APIKeys implements APIKeysNamespace {
     };
   }
 
-  async getAll(params?: GetAPIKeysParams): Promise<APIKeyResource[]> {
-    return BaseResource.clerk
-      .getFapiClient()
-      .request<{ api_keys: ApiKeyJSON[] }>({
-        ...(await this.getBaseFapiProxyOptions()),
-        method: 'GET',
-        path: '/api_keys',
-        search: {
-          subject: params?.subject ?? BaseResource.clerk.organization?.id ?? BaseResource.clerk.user?.id ?? '',
-          // TODO: (rob) Remove when server-side pagination is implemented.
-          limit: '100',
-        },
-      })
-      .then(res => {
-        const apiKeysJSON = res.payload as unknown as { api_keys: ApiKeyJSON[] };
-        return apiKeysJSON.api_keys.map(json => new APIKey(json));
-      });
+  async getAll(params?: GetAPIKeysParams): Promise<ClerkPaginatedResponse<APIKeyResource>> {
+    return BaseResource._fetch({
+      ...(await this.getBaseFapiProxyOptions()),
+      method: 'GET',
+      path: '/api_keys',
+      search: convertPageToOffsetSearchParams({
+        ...params,
+        subject: params?.subject ?? BaseResource.clerk.organization?.id ?? BaseResource.clerk.user?.id ?? '',
+        query: params?.query ?? '',
+      }),
+    }).then(res => {
+      const { data: apiKeys, total_count } = res as unknown as ClerkPaginatedResponse<ApiKeyJSON>;
+
+      return {
+        total_count,
+        data: apiKeys.map(apiKey => new APIKey(apiKey)),
+      };
+    });
   }
 
   async create(params: CreateAPIKeyParams): Promise<APIKeyResource> {

packages/clerk-js/src/ui/components/ApiKeys/ApiKeys.tsx

@@ -1,8 +1,7 @@
 import { isClerkAPIResponseError } from '@clerk/shared/error';
-import { useClerk, useOrganization, useUser } from '@clerk/shared/react';
+import { __experimental_useAPIKeys as useAPIKeys, useClerk, useOrganization, useUser } from '@clerk/shared/react';
 import type { CreateAPIKeyParams } from '@clerk/shared/types';
 import { lazy, useState } from 'react';
-import { useSWRConfig } from 'swr';
 import useSWRMutation from 'swr/mutation';
 
 import { useProtect } from '@/ui/common';
@@ -22,14 +21,15 @@ import { Action } from '@/ui/elements/Action';
 import { useCardState, withCardStateProvider } from '@/ui/elements/contexts';
 import { InputWithIcon } from '@/ui/elements/InputWithIcon';
 import { Pagination } from '@/ui/elements/Pagination';
+import { useDebounce } from '@/ui/hooks';
 import { MagnifyingGlass } from '@/ui/icons';
 import { mqu } from '@/ui/styledSystem';
 import { isOrganizationId } from '@/utils';
 
 import { ApiKeysTable } from './ApiKeysTable';
 import type { OnCreateParams } from './CreateApiKeyForm';
 import { CreateApiKeyForm } from './CreateApiKeyForm';
-import { useApiKeys } from './useApiKeys';
+import { useAPIKeysPagination } from './utils';
 
 type APIKeysPageProps = {
   subject: string;
@@ -49,38 +49,55 @@ const CopyApiKeyModal = lazy(() =>
   })),
 );
 
+const apiKeysSearchDebounceMs = 500;
+
 export const APIKeysPage = ({ subject, perPage, revokeModalRoot }: APIKeysPageProps) => {
   const isOrg = isOrganizationId(subject);
   const canReadAPIKeys = useProtect({ permission: 'org:sys_api_keys:read' });
   const canManageAPIKeys = useProtect({ permission: 'org:sys_api_keys:manage' });
 
+  const [searchValue, setSearchValue] = useState('');
+  const debouncedSearchValue = useDebounce(searchValue, apiKeysSearchDebounceMs);
+  const query = debouncedSearchValue.trim();
+
   const {
-    apiKeys,
+    data: apiKeys,
     isLoading,
-    search,
-    setSearch,
+    isFetching,
+    page,
+    fetchPage,
+    pageCount,
+    count: itemCount,
+  } = useAPIKeys({
+    subject,
+    pageSize: perPage ?? 5,
+    query,
+    keepPreviousData: true,
+    enabled: isOrg ? canReadAPIKeys : true,
+  });
+
+  const { invalidateAll } = useAPIKeysPagination({
+    query,
     page,
-    setPage,
     pageCount,
-    itemCount,
-    startingRow,
-    endingRow,
-    cacheKey,
-  } = useApiKeys({ subject, perPage, enabled: isOrg ? canReadAPIKeys : true });
+    isFetching,
+    subject,
+    fetchPage,
+  });
+
+  const startingRow = itemCount > 0 ? Math.max(0, (page - 1) * (perPage ?? 5)) + 1 : 0;
+  const endingRow = Math.min(page * (perPage ?? 5), itemCount);
+
+  const handlePageChange = (newPage: number) => {
+    fetchPage(newPage);
+  };
   const card = useCardState();
   const clerk = useClerk();
   const {
     data: createdApiKey,
     trigger: createApiKey,
     isMutating,
-  } = useSWRMutation(
-    {
-      ...cacheKey,
-      action: 'create',
-    },
-    (_key, { arg }: { arg: CreateAPIKeyParams }) => clerk.apiKeys.create(arg),
-  );
-  const { mutate: mutateApiKeys } = useSWRConfig();
+  } = useSWRMutation('api-keys-create', (_key, { arg }: { arg: CreateAPIKeyParams }) => clerk.apiKeys.create(arg));
   const { t } = useLocalizations();
   const [isRevokeModalOpen, setIsRevokeModalOpen] = useState(false);
   const [selectedApiKeyId, setSelectedApiKeyId] = useState('');
@@ -93,7 +110,7 @@ export const APIKeysPage = ({ subject, perPage, revokeModalRoot }: APIKeysPagePr
         ...params,
         subject,
       });
-      void mutateApiKeys(cacheKey);
+      invalidateAll();
       card.setError(undefined);
       setIsCopyModalOpen(true);
     } catch (err: any) {
@@ -133,12 +150,17 @@ export const APIKeysPage = ({ subject, perPage, revokeModalRoot }: APIKeysPagePr
           <Box elementDescriptor={descriptors.apiKeysSearchBox}>
             <InputWithIcon
               placeholder={t(localizationKeys('apiKeys.action__search'))}
-              leftIcon={<Icon icon={MagnifyingGlass} />}
-              value={search}
-              onChange={e => {
-                setSearch(e.target.value);
-                setPage(1);
-              }}
+              leftIcon={
+                <Icon
+                  icon={MagnifyingGlass}
+                  sx={t => ({ color: t.colors.$colorMutedForeground })}
+                />
+              }
+              value={searchValue}
+              type='search'
+              autoCapitalize='none'
+              spellCheck={false}
+              onChange={e => setSearchValue(e.target.value)}
               elementDescriptor={descriptors.apiKeysSearchInput}
             />
           </Box>
@@ -183,19 +205,17 @@ export const APIKeysPage = ({ subject, perPage, revokeModalRoot }: APIKeysPagePr
         elementDescriptor={descriptors.apiKeysTable}
         canManageAPIKeys={(isOrg && canManageAPIKeys) || !isOrg}
       />
-      {itemCount > (perPage ?? 5) && (
+      {(itemCount > (perPage ?? 5) || pageCount > 1) && (
         <Pagination
           count={pageCount}
-          page={page}
-          onChange={setPage}
+          page={Math.min(page, pageCount)}
+          onChange={handlePageChange}
           siblingCount={1}
           rowInfo={{ allRowsCount: itemCount, startingRow, endingRow }}
         />
       )}
 
-      {/* Modals */}
       <RevokeAPIKeyConfirmationModal
-        subject={subject}
         isOpen={isRevokeModalOpen}
         onOpen={() => setIsRevokeModalOpen(true)}
         onClose={() => {
@@ -205,6 +225,7 @@ export const APIKeysPage = ({ subject, perPage, revokeModalRoot }: APIKeysPagePr
         }}
         apiKeyId={selectedApiKeyId}
         apiKeyName={selectedApiKeyName}
+        onRevokeSuccess={invalidateAll}
         modalRoot={revokeModalRoot}
       />
     </Col>

packages/clerk-js/src/ui/components/ApiKeys/RevokeAPIKeyConfirmationModal.tsx

@@ -1,5 +1,4 @@
 import { useClerk } from '@clerk/shared/react';
-import { useSWRConfig } from 'swr';
 
 import { descriptors } from '@/ui/customizables';
 import { Card } from '@/ui/elements/Card';
@@ -12,26 +11,25 @@ import { useFormControl } from '@/ui/utils/useFormControl';
 import { ApiKeyModal } from './ApiKeyModal';
 
 type RevokeAPIKeyConfirmationModalProps = {
-  subject: string;
   isOpen: boolean;
   onOpen: () => void;
   onClose: () => void;
   apiKeyId?: string;
   apiKeyName: string;
+  onRevokeSuccess?: () => void;
   modalRoot?: React.MutableRefObject<HTMLElement | null>;
 };
 
 export const RevokeAPIKeyConfirmationModal = ({
-  subject,
   isOpen,
   onOpen,
   onClose,
   apiKeyId,
   apiKeyName,
+  onRevokeSuccess,
   modalRoot,
 }: RevokeAPIKeyConfirmationModalProps) => {
   const clerk = useClerk();
-  const { mutate } = useSWRConfig();
   const { t } = useLocalizations();
 
   const revokeField = useFormControl('apiKeyRevokeConfirmation', '', {
@@ -55,9 +53,7 @@ export const RevokeAPIKeyConfirmationModal = ({
     }
 
     await clerk.apiKeys.revoke({ apiKeyID: apiKeyId });
-    const cacheKey = { key: 'api-keys', subject };
-
-    void mutate(cacheKey);
+    onRevokeSuccess?.();
     handleClose();
   };