From 7b29a0a0eccd5e4cd22b6e0467b53e87959754e7 Mon Sep 17 00:00:00 2001 From: Kyle MacDonald Date: Tue, 27 May 2025 16:02:44 -0400 Subject: [PATCH 1/9] stub in basic docs for component --- docs/components/api-keys.mdx | 44 ++++++++++++++++++++++++++++++++++++ docs/manifest.json | 12 ++++++++++ 2 files changed, 56 insertions(+) create mode 100644 docs/components/api-keys.mdx diff --git a/docs/components/api-keys.mdx b/docs/components/api-keys.mdx new file mode 100644 index 0000000000..db03512570 --- /dev/null +++ b/docs/components/api-keys.mdx @@ -0,0 +1,44 @@ +--- +title: '`` component' +description: Clerk's component for managing API keys. +--- + +The `` component is used to manage API keys for your application. It allows you to create, edit, and revoke API keys for your application. + +To utilize the `` component, you must first enable API keys in the Clerk Dashboard. + +## Properties + +All props are optional. + + + - `type` + - `'api_key'` + + The type of API key to filter by. Currently, only 'api\_key' is supported. + + --- + + - `perPage` + - `number` + + The number of API keys to show per page. Defaults to 5. + + --- + + - `appearance` + - [Appearance](/docs/customization/overview) | undefined + + Optional object to style your components. Will only affect [Clerk components](/docs/components/overview) and not [Account Portal](/docs/account-portal/overview) pages. + + --- + + - `fallback?` + - `ReactNode` + + An optional element to be rendered while the component is mounting. + + +## Customization + +To learn about how to customize Clerk components, see the [customization guide](/docs/customization/overview). diff --git a/docs/manifest.json b/docs/manifest.json index 9d97f34432..9c56b2ea7a 100644 --- a/docs/manifest.json +++ b/docs/manifest.json @@ -955,6 +955,18 @@ ] ] }, + { + "title": "API Keys Components", + "items": [ + [ + { + "title": "``", + "wrap": false, + "href": "/docs/components/api-keys" + } + ] + ] + }, { "title": "Control Components", "items": [ From 920ac873c8d9ba4805924409916ee7f4e5ff7edc Mon Sep 17 00:00:00 2001 From: Kyle MacDonald Date: Tue, 27 May 2025 16:09:42 -0400 Subject: [PATCH 2/9] add note about being in early preview --- docs/components/api-keys.mdx | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/components/api-keys.mdx b/docs/components/api-keys.mdx index db03512570..a78ffcc91d 100644 --- a/docs/components/api-keys.mdx +++ b/docs/components/api-keys.mdx @@ -7,6 +7,9 @@ The `` component is used to manage API keys for your application. It To utilize the `` component, you must first enable API keys in the Clerk Dashboard. +> [!WARNING] +> The `` component is currently in early preview. To use this component, you need to have your instance flagged for API keys. Contact Clerk support to enable this feature for your instance. + ## Properties All props are optional. From 87fa556babe20beff5f93ce8aa7a44a262ee9e38 Mon Sep 17 00:00:00 2001 From: wobsoriano Date: Tue, 27 May 2025 16:04:00 -0700 Subject: [PATCH 3/9] add usage section --- docs/components/api-keys.mdx | 26 ++++++++++++++++++++++++++ 1 file changed, 26 insertions(+) diff --git a/docs/components/api-keys.mdx b/docs/components/api-keys.mdx index a78ffcc91d..dffb535a81 100644 --- a/docs/components/api-keys.mdx +++ b/docs/components/api-keys.mdx @@ -42,6 +42,32 @@ All props are optional. An optional element to be rendered while the component is mounting. +## Usage with frameworks + +The following example includes a basic implementation of the `` component. You can use this as a starting point for your own implementation. + + + + ```tsx {{ filename: 'app/api-keys/page.tsx' }} + import { APIKeys } from '@clerk/nextjs' + + export default function Page() { + return + } + ``` + + + + ```tsx {{ filename: 'src/api-keys.tsx' }} + import { APIKeys } from '@clerk/clerk-react' + + export default function APIKeysPage() { + return + } + ``` + + + ## Customization To learn about how to customize Clerk components, see the [customization guide](/docs/customization/overview). From 18f098ffed6561fc23ef0bf388f8140342e9b16f Mon Sep 17 00:00:00 2001 From: wobsoriano Date: Wed, 28 May 2025 11:34:27 -0700 Subject: [PATCH 4/9] chore: rename component --- docs/components/api-keys.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/components/api-keys.mdx b/docs/components/api-keys.mdx index dffb535a81..51c06a35c3 100644 --- a/docs/components/api-keys.mdx +++ b/docs/components/api-keys.mdx @@ -44,7 +44,7 @@ All props are optional. ## Usage with frameworks -The following example includes a basic implementation of the `` component. You can use this as a starting point for your own implementation. +The following example includes a basic implementation of the `` component. You can use this as a starting point for your own implementation. From 54ac6c3c91ad8b7115c254a9da0ffe0a0426815d Mon Sep 17 00:00:00 2001 From: wobsoriano Date: Thu, 29 May 2025 18:42:46 -0700 Subject: [PATCH 5/9] add JS usage --- docs/components/api-keys.mdx | 92 ++++++++++++++++++++++++++++++++++++ 1 file changed, 92 insertions(+) diff --git a/docs/components/api-keys.mdx b/docs/components/api-keys.mdx index 51c06a35c3..487826ffc1 100644 --- a/docs/components/api-keys.mdx +++ b/docs/components/api-keys.mdx @@ -68,6 +68,98 @@ The following example includes a basic implementation of the `` compo + + ## Usage with JavaScript + + The following methods available on an instance of the [`Clerk`](/docs/references/javascript/clerk) class are used to render and control the `` component: + + - [`mountApiKeys()`](#mount-api-keys) + - [`unmountApiKeys()`](#unmount-api-keys) + + The following examples assume that you followed the [quickstart](/docs/quickstarts/javascript) to add Clerk to your JavaScript app. + + ### `mountApiKeys()` + + ```typescript + function mountApiKeys(node: HTMLDivElement, props?: APIKeysProps): void + ``` + + #### `mountApiKeys()` params + + + - `node` + - [`HTMLDivElement`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLDivElement) + + The container `
` element used to render in the `` component + + --- + + - `props?` + - [`APIKeysProps`](#properties) + + The properties to pass to the `` component + + + #### `mountApiKeys()` usage + + ```js {{ filename: 'main.js', mark: [15] }} + import { Clerk } from '@clerk/clerk-js' + + // Initialize Clerk with your Clerk Publishable Key + const clerkPubKey = import.meta.env.VITE_CLERK_PUBLISHABLE_KEY + + const clerk = new Clerk(clerkPubKey) + await clerk.load() + + document.getElementById('app').innerHTML = ` +
+ ` + + const apiKeysDiv = document.getElementById('api-keys') + + clerk.mountApiKeys(apiKeysDiv) + ``` + + ### `unmountApiKeys()` + + ```typescript + function unmountApiKeys(node: HTMLDivElement): void + ``` + + #### `unmountApiKeys()` params + + + - `node` + - [`HTMLDivElement`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLDivElement) + + The container `
` element with a rendered `` component instance + + + #### `unmountApiKeys()` usage + + ```js {{ filename: 'main.js', mark: [19] }} + import { Clerk } from '@clerk/clerk-js' + + // Initialize Clerk with your Clerk Publishable Key + const clerkPubKey = import.meta.env.VITE_CLERK_PUBLISHABLE_KEY + + const clerk = new Clerk(clerkPubKey) + await clerk.load() + + document.getElementById('app').innerHTML = ` +
+ ` + + const apiKeysDiv = document.getElementById('api-keys') + + clerk.mountApiKeys(apiKeysDiv) + + // ... + + clerk.unmountApiKeys(apiKeysDiv) + ``` + + ## Customization To learn about how to customize Clerk components, see the [customization guide](/docs/customization/overview). From 5ba3c6929ff9d4a54ed683d03e0dc89261b5a927 Mon Sep 17 00:00:00 2001 From: wobsoriano Date: Tue, 17 Jun 2025 11:17:25 -0700 Subject: [PATCH 6/9] chore: add react router and tanstack usage --- docs/components/api-keys.mdx | 27 ++++++++++++++++++++++++++- 1 file changed, 26 insertions(+), 1 deletion(-) diff --git a/docs/components/api-keys.mdx b/docs/components/api-keys.mdx index 487826ffc1..93c6acd43f 100644 --- a/docs/components/api-keys.mdx +++ b/docs/components/api-keys.mdx @@ -46,7 +46,7 @@ All props are optional. The following example includes a basic implementation of the `` component. You can use this as a starting point for your own implementation. - + ```tsx {{ filename: 'app/api-keys/page.tsx' }} import { APIKeys } from '@clerk/nextjs' @@ -66,6 +66,31 @@ The following example includes a basic implementation of the `` compo } ``` + + + ```tsx {{ filename: 'app/routes/api-keys.tsx' }} + import { APIKeys } from '@clerk/react-router' + + export default function APIKeysPage() { + return + } + ``` + + + + ```tsx {{ filename: 'src/routes/api-keys.tsx' }} + import { APIKeys } from '@clerk/tanstack-react-start' + import { createFileRoute } from '@tanstack/react-router' + + export const Route = createFileRoute('/api-keys')({ + component: APIKeysPage, + }) + + function APIKeysPage() { + return + } + ``` + From 2bba8ea8f71f9bde3e48a87da548af2326b48414 Mon Sep 17 00:00:00 2001 From: wobsoriano Date: Tue, 17 Jun 2025 11:19:19 -0700 Subject: [PATCH 7/9] fix incorrect component --- docs/components/api-keys.mdx | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/components/api-keys.mdx b/docs/components/api-keys.mdx index 93c6acd43f..089d0c5832 100644 --- a/docs/components/api-keys.mdx +++ b/docs/components/api-keys.mdx @@ -61,7 +61,7 @@ The following example includes a basic implementation of the `` compo ```tsx {{ filename: 'src/api-keys.tsx' }} import { APIKeys } from '@clerk/clerk-react' - export default function APIKeysPage() { + export default function Page() { return } ``` @@ -71,7 +71,7 @@ The following example includes a basic implementation of the `` compo ```tsx {{ filename: 'app/routes/api-keys.tsx' }} import { APIKeys } from '@clerk/react-router' - export default function APIKeysPage() { + export default function Page() { return } ``` @@ -83,11 +83,11 @@ The following example includes a basic implementation of the `` compo import { createFileRoute } from '@tanstack/react-router' export const Route = createFileRoute('/api-keys')({ - component: APIKeysPage, + component: Page, }) - function APIKeysPage() { - return + function Page() { + return } ``` From 252821d9222170b9691e5c608621ff086b2f8aa8 Mon Sep 17 00:00:00 2001 From: wobsoriano Date: Thu, 21 Aug 2025 11:02:32 -0700 Subject: [PATCH 8/9] explain scoping between org and users and add vue example --- docs/components/api-keys.mdx | 16 +++++++++++++++- 1 file changed, 15 insertions(+), 1 deletion(-) diff --git a/docs/components/api-keys.mdx b/docs/components/api-keys.mdx index 089d0c5832..5bbbfec402 100644 --- a/docs/components/api-keys.mdx +++ b/docs/components/api-keys.mdx @@ -5,6 +5,8 @@ description: Clerk's component for managing API keys. The `` component is used to manage API keys for your application. It allows you to create, edit, and revoke API keys for your application. +The component automatically manages API keys based on the user's current context. When the user has an active organization selected, all operations are scoped to that organization. Otherwise, operations are user-scoped. + To utilize the `` component, you must first enable API keys in the Clerk Dashboard. > [!WARNING] @@ -46,7 +48,7 @@ All props are optional. The following example includes a basic implementation of the `` component. You can use this as a starting point for your own implementation. - + ```tsx {{ filename: 'app/api-keys/page.tsx' }} import { APIKeys } from '@clerk/nextjs' @@ -91,6 +93,18 @@ The following example includes a basic implementation of the `` compo } ``` + + + ```vue {{ filename: 'api-keys.vue' }} + + + + ``` + From 714f745cfd18b0ec54e40f25ae612b1686c1df13 Mon Sep 17 00:00:00 2001 From: wobsoriano Date: Thu, 21 Aug 2025 11:02:52 -0700 Subject: [PATCH 9/9] remove extra word --- docs/components/api-keys.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/components/api-keys.mdx b/docs/components/api-keys.mdx index 5bbbfec402..457696ae34 100644 --- a/docs/components/api-keys.mdx +++ b/docs/components/api-keys.mdx @@ -5,7 +5,7 @@ description: Clerk's component for managing API keys. The `` component is used to manage API keys for your application. It allows you to create, edit, and revoke API keys for your application. -The component automatically manages API keys based on the user's current context. When the user has an active organization selected, all operations are scoped to that organization. Otherwise, operations are user-scoped. +The component manages API keys based on the user's current context. When the user has an active organization selected, all operations are scoped to that organization. Otherwise, operations are user-scoped. To utilize the `` component, you must first enable API keys in the Clerk Dashboard.