Skip to content

chore(backend): Add API keys list method #6948

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Oct 9, 2025
Merged

chore(backend): Add API keys list method #6948

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
868c6bd
chore(backend): Add API keys list method
wobsoriano Oct 9, 2025
9201009
chore: add changeset
wobsoriano Oct 9, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions .changeset/mighty-kids-joke.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
"@clerk/backend": patch
---

Added API keys list method to the backend SDK client
25 changes: 24 additions & 1 deletion packages/backend/src/api/endpoints/APIKeysApi.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,17 +1,32 @@
import type { ClerkPaginationRequest } from '@clerk/types';

import { joinPaths } from '../../util/path';
import type { APIKey } from '../resources/APIKey';
import { AbstractAPI } from './AbstractApi';

const basePath = '/api_keys';

type GetAPIKeyListParams = ClerkPaginationRequest<{
/**
* The user or organization ID to query API keys by
*/
subject: string;
/**
* Whether to include invalid API keys.
*
* @default false
*/
includeInvalid?: boolean;
}>;

type CreateAPIKeyParams = {
type?: 'api_key';
/**
* API key name
*/
name: string;
/**
* user or organization ID the API key is associated with
* The user or organization ID to associate the API key with
*/
subject: string;
/**
Expand All @@ -36,6 +51,14 @@ type RevokeAPIKeyParams = {
};

export class APIKeysAPI extends AbstractAPI {
async list(queryParams: GetAPIKeyListParams) {
return this.request<APIKey[]>({
method: 'GET',
path: basePath,
queryParams,
});
}
Comment on lines +54 to +60
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🛠️ Refactor suggestion | 🟠 Major

🧩 Analysis chain

Add explicit return type, JSDoc documentation, and parameter validation.

The method has several issues that should be addressed:

  1. Missing explicit return type: Per coding guidelines, public APIs must have explicit return types for clarity and type safety.
  2. Missing JSDoc documentation: Per coding guidelines, all public APIs must be documented with JSDoc comments.
  3. Missing parameter validation: The subject parameter is required but not validated. Other methods in this class (e.g., revoke, getSecret) validate ID parameters using this.requireId().

Apply this diff to add return type, JSDoc, and validation:

+  /**
+   * List API keys for a user or organization
+   * 
+   * @param queryParams - Query parameters including subject, pagination, and filter options
+   * @returns Promise resolving to an array of APIKey objects
+   */
-  async list(queryParams: GetAPIKeyListParams) {
+  async list(queryParams: GetAPIKeyListParams): Promise<APIKey[]> {
+    this.requireId(queryParams.subject);
+
     return this.request<APIKey[]>({
       method: 'GET',
       path: basePath,
       queryParams,
     });
   }

Additionally, verify whether the API response includes pagination metadata (total count, hasMore, etc.) or just returns an array:

🏁 Script executed:

#!/bin/bash
# Description: Check how other list methods in the API handle pagination responses

# Search for other list methods to understand the pagination pattern
ast-grep --pattern $'async list($$$) {
  $$$
  return this.request$$$
}'

# Also check if there are pagination response types defined
rg -nP --type=ts 'Paginated|PaginationResponse|ListResponse' -C3

Length of output: 99058

🏁 Script executed:

#!/bin/bash
rg -nP --type=ts 'GetAPIKeyListParams\b' -C3 packages/backend/src/api

Length of output: 1054

Use paginated response type and validate subject ID

  • Validate the required subject via this.requireId(queryParams.subject) before calling the API.
  • Change the signature to
    async list(queryParams: GetAPIKeyListParams): Promise<PaginatedResourceResponse<APIKey[]>>
    and update the request generic to PaginatedResourceResponse<APIKey[]>.
🤖 Prompt for AI Agents 
In packages/backend/src/api/endpoints/APIKeysApi.ts around lines 54 to 60, the
list method must validate the required subject ID and return a paginated
response type: call this.requireId(queryParams.subject) at the top of the method
to validate the subject, change the method signature to async list(queryParams:
GetAPIKeyListParams): Promise<PaginatedResourceResponse<APIKey[]>> and update
the this.request generic to PaginatedResourceResponse<APIKey[]> so the API call
returns the paginated shape.


async create(params: CreateAPIKeyParams) {
return this.request<APIKey>({
method: 'POST',
Expand Down
Loading