chore(backend): Add API keys list method #6948
Conversation
🦋 Changeset detectedLatest commit: 9201009 The changes in this PR will be included in the next version bump. This PR includes changesets to release 11 packages
Not sure what this means? Click here to learn what changesets are. Click here if you're a maintainer who wants to add another changeset to this PR |
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
WalkthroughAdds a changeset patch entry for @clerk/backend and implements an API keys list capability in the backend SDK: new pagination params type, a list method in APIKeysAPI that GETs /api_keys, and a minor doc tweak to CreateAPIKeyParams.description. Changes
Sequence Diagram(s)sequenceDiagram
autonumber
actor DevApp as Developer App
participant SDK as BackendSdkClient
participant APIKeys as APIKeysAPI
participant HTTP as HTTP Client
participant Clerk as Clerk API
DevApp->>SDK: listAPIKeys({ subject, includeInvalid?, pagination... })
SDK->>APIKeys: list(queryParams)
APIKeys->>HTTP: GET /api_keys?subject=...&include_invalid=...&limit=...&offset=...
HTTP->>Clerk: Request
Clerk-->>HTTP: 200 OK (APIKey[])
HTTP-->>APIKeys: APIKey[]
APIKeys-->>SDK: APIKey[]
SDK-->>DevApp: APIKey[]
note over DevApp,APIKeys: subject (required), includeInvalid (optional)
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10–15 minutes Poem
Pre-merge checks and finishing touches✅ Passed checks (3 passed)
✨ Finishing touches
🧪 Generate unit tests (beta)
Comment |
@clerk/agent-toolkit
@clerk/astro
@clerk/backend
@clerk/chrome-extension
@clerk/clerk-js
@clerk/dev-cli
@clerk/elements
@clerk/clerk-expo
@clerk/expo-passkeys
@clerk/express
@clerk/fastify
@clerk/localizations
@clerk/nextjs
@clerk/nuxt
@clerk/clerk-react
@clerk/react-router
@clerk/remix
@clerk/shared
@clerk/tanstack-react-start
@clerk/testing
@clerk/themes
@clerk/types
@clerk/upgrade
@clerk/vue
commit: |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
📜 Review details
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Disabled knowledge base sources:
- Linear integration is disabled by default for public repositories
You can enable these sources in your CodeRabbit configuration.
📒 Files selected for processing (2)
.changeset/mighty-kids-joke.md(1 hunks)packages/backend/src/api/endpoints/APIKeysApi.ts(2 hunks)
🧰 Additional context used
📓 Path-based instructions (7)
**/*.{js,jsx,ts,tsx}
📄 CodeRabbit inference engine (.cursor/rules/development.mdc)
**/*.{js,jsx,ts,tsx}: All code must pass ESLint checks with the project's configuration
Follow established naming conventions (PascalCase for components, camelCase for variables)
Maintain comprehensive JSDoc comments for public APIs
Use dynamic imports for optional features
All public APIs must be documented with JSDoc
Provide meaningful error messages to developers
Include error recovery suggestions where applicable
Log errors appropriately for debugging
Lazy load components and features when possible
Implement proper caching strategies
Use efficient data structures and algorithms
Profile and optimize critical paths
Validate all inputs and sanitize outputs
Implement proper logging with different levels
Files:
packages/backend/src/api/endpoints/APIKeysApi.ts
**/*.{js,jsx,ts,tsx,json,css,scss,md,yaml,yml}
📄 CodeRabbit inference engine (.cursor/rules/development.mdc)
Use Prettier for consistent code formatting
Files:
packages/backend/src/api/endpoints/APIKeysApi.ts
packages/**/*.{ts,tsx}
📄 CodeRabbit inference engine (.cursor/rules/development.mdc)
TypeScript is required for all packages
Files:
packages/backend/src/api/endpoints/APIKeysApi.ts
packages/**/*.{ts,tsx,d.ts}
📄 CodeRabbit inference engine (.cursor/rules/development.mdc)
Packages should export TypeScript types alongside runtime code
Files:
packages/backend/src/api/endpoints/APIKeysApi.ts
**/*.{ts,tsx}
📄 CodeRabbit inference engine (.cursor/rules/development.mdc)
Use proper TypeScript error types
**/*.{ts,tsx}: Always define explicit return types for functions, especially public APIs
Use proper type annotations for variables and parameters where inference isn't clear
Avoidanytype - preferunknownwhen type is uncertain, then narrow with type guards
Useinterfacefor object shapes that might be extended
Usetypefor unions, primitives, and computed types
Preferreadonlyproperties for immutable data structures
Useprivatefor internal implementation details
Useprotectedfor inheritance hierarchies
Usepublicexplicitly for clarity in public APIs
Preferreadonlyfor properties that shouldn't change after construction
Prefer composition and interfaces over deep inheritance chains
Use mixins for shared behavior across unrelated classes
Implement dependency injection for loose coupling
Let TypeScript infer when types are obvious
Useconst assertionsfor literal types:as const
Usesatisfiesoperator for type checking without widening
Use mapped types for transforming object types
Use conditional types for type-level logic
Leverage template literal types for string manipulation
Use ES6 imports/exports consistently
Use default exports sparingly, prefer named exports
Use type-only imports:import type { ... } from ...
Noanytypes without justification
Proper error handling with typed errors
Consistent use ofreadonlyfor immutable data
Proper generic constraints
No unused type parameters
Proper use of utility types instead of manual type construction
Type-only imports where possible
Proper tree-shaking friendly exports
No circular dependencies
Efficient type computations (avoid deep recursion)
Files:
packages/backend/src/api/endpoints/APIKeysApi.ts
**/*.{js,ts,tsx,jsx}
📄 CodeRabbit inference engine (.cursor/rules/monorepo.mdc)
Support multiple Clerk environment variables (CLERK_, NEXT_PUBLIC_CLERK_, etc.) for configuration.
Files:
packages/backend/src/api/endpoints/APIKeysApi.ts
.changeset/**
📄 CodeRabbit inference engine (.cursor/rules/monorepo.mdc)
Automated releases must use Changesets.
Files:
.changeset/mighty-kids-joke.md
🧬 Code graph analysis (1)
packages/backend/src/api/endpoints/APIKeysApi.ts (3)
packages/types/src/pagination.ts (1)
ClerkPaginationRequest(5-14)packages/types/src/clerk.ts (1)
CreateAPIKeyParams(1882-1888)packages/backend/src/api/resources/APIKey.ts (1)
APIKey(3-43)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (28)
- GitHub Check: Integration Tests (machine, chrome)
- GitHub Check: Integration Tests (nextjs, chrome, 15)
- GitHub Check: Integration Tests (sessions:staging, chrome)
- GitHub Check: Integration Tests (nextjs, chrome, 14)
- GitHub Check: Integration Tests (custom, chrome)
- GitHub Check: Integration Tests (billing, chrome)
- GitHub Check: Integration Tests (handshake:staging, chrome)
- GitHub Check: Integration Tests (nuxt, chrome)
- GitHub Check: Integration Tests (vue, chrome)
- GitHub Check: Integration Tests (astro, chrome)
- GitHub Check: Integration Tests (handshake, chrome)
- GitHub Check: Integration Tests (tanstack-react-start, chrome)
- GitHub Check: Integration Tests (sessions, chrome)
- GitHub Check: Integration Tests (tanstack-react-router, chrome)
- GitHub Check: Integration Tests (expo-web, chrome)
- GitHub Check: Integration Tests (quickstart, chrome)
- GitHub Check: Integration Tests (elements, chrome)
- GitHub Check: Integration Tests (react-router, chrome)
- GitHub Check: Integration Tests (localhost, chrome)
- GitHub Check: Integration Tests (ap-flows, chrome)
- GitHub Check: Integration Tests (generic, chrome)
- GitHub Check: Integration Tests (express, chrome)
- GitHub Check: Publish with pkg-pr-new
- GitHub Check: Unit Tests (18, --filter=@clerk/astro --filter=@clerk/backend --filter=@clerk/express --filter=@c...
- GitHub Check: Unit Tests (22, **)
- GitHub Check: Static analysis
- GitHub Check: semgrep-cloud-platform/scan
- GitHub Check: semgrep-cloud-platform/scan
🔇 Additional comments (4)
packages/backend/src/api/endpoints/APIKeysApi.ts (3)
1-1: LGTM!Type-only import follows best practices for tree-shaking and is properly used in the new
GetAPIKeyListParamstype.
9-20: LGTM!The type definition is well-structured with clear JSDoc documentation. The use of
ClerkPaginationRequestas a base type provides consistent pagination behavior across the SDK.
29-29: LGTM!The documentation wording is clearer and more actionable.
.changeset/mighty-kids-joke.md (1)
1-5: LGTM!The changeset correctly documents this as a patch-level change to
@clerk/backend. The description accurately reflects the addition of the API keys list method.
| async list(queryParams: GetAPIKeyListParams) { | ||
| return this.request<APIKey[]>({ | ||
| method: 'GET', | ||
| path: basePath, | ||
| queryParams, | ||
| }); | ||
| } |
There was a problem hiding this comment.
🛠️ Refactor suggestion | 🟠 Major
🧩 Analysis chain
Add explicit return type, JSDoc documentation, and parameter validation.
The method has several issues that should be addressed:
- Missing explicit return type: Per coding guidelines, public APIs must have explicit return types for clarity and type safety.
- Missing JSDoc documentation: Per coding guidelines, all public APIs must be documented with JSDoc comments.
- Missing parameter validation: The
subjectparameter is required but not validated. Other methods in this class (e.g.,revoke,getSecret) validate ID parameters usingthis.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' -C3Length of output: 99058
🏁 Script executed:
#!/bin/bash
rg -nP --type=ts 'GetAPIKeyListParams\b' -C3 packages/backend/src/apiLength of output: 1054
Use paginated response type and validate subject ID
- Validate the required
subjectviathis.requireId(queryParams.subject)before calling the API. - Change the signature to
async list(queryParams: GetAPIKeyListParams): Promise<PaginatedResourceResponse<APIKey[]>>
and update the request generic toPaginatedResourceResponse<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.
Description
This PR adds API keys list method to the backend SDK client
Checklist
pnpm testruns as expected.pnpm buildruns as expected.Type of change
Summary by CodeRabbit
New Features
Documentation