diff --git a/docs/components/api-keys.mdx b/docs/components/api-keys.mdx new file mode 100644 index 0000000000..457696ae34 --- /dev/null +++ b/docs/components/api-keys.mdx @@ -0,0 +1,204 @@ +--- +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. + +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. + +> [!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. + + + - `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. + + +## 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 Page() { + return + } + ``` + + + + ```tsx {{ filename: 'app/routes/api-keys.tsx' }} + import { APIKeys } from '@clerk/react-router' + + export default function Page() { + 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: Page, + }) + + function Page() { + return + } + ``` + + + + ```vue {{ filename: 'api-keys.vue' }} + + + + ``` + + + + + ## 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). 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": [