feat(clerk-js,clerk-react,nextjs): Introduce <APIKeys /> AIO component

.changeset/fluffy-numbers-stick.md

@@ -0,0 +1,6 @@
+---
+'@clerk/localizations': patch
+'@clerk/types': patch
+---
+
+Add TypeScript types and en-US localization for upcoming `<APIKeys />` component. This component will initially be in early access.

.changeset/ninety-candles-sleep.md

@@ -0,0 +1,7 @@
+---
+'@clerk/clerk-js': minor
+'@clerk/nextjs': minor
+'@clerk/clerk-react': minor
+---
+
+Add `<APIKeys />` component. This component will initially be in early access and not recommended for production usage just yet.

.typedoc/__tests__/__snapshots__/file-structure.test.ts.snap

@@ -129,6 +129,7 @@ exports[`Typedoc output > should have a deliberate file structure 1`] = `
  "nextjs/create-sync-get-auth.mdx",
  "nextjs/current-user.mdx",
  "nextjs/get-auth.mdx",
+ "clerk-react/api-keys.mdx",
  "clerk-react/clerk-provider-props.mdx",
  "clerk-react/protect.mdx",
  "clerk-react/redirect-to-create-organization.mdx",

packages/chrome-extension/src/__tests__/__snapshots__/exports.test.ts.snap

@@ -2,6 +2,7 @@
 
 exports[`public exports should not include a breaking change 1`] = `
 [
+ "APIKeys",
  "AuthenticateWithRedirectCallback",
  "ClerkDegraded",
  "ClerkFailed",

packages/clerk-js/bundlewatch.config.json

@@ -1,10 +1,10 @@
 {
  "files": [
- { "path": "./dist/clerk.js", "maxSize": "605kB" },
- { "path": "./dist/clerk.browser.js", "maxSize": "69.3KB" },
+ { "path": "./dist/clerk.js", "maxSize": "608.89kB" },
+ { "path": "./dist/clerk.browser.js", "maxSize": "70.15KB" },
  { "path": "./dist/clerk.legacy.browser.js", "maxSize": "113KB" },
- { "path": "./dist/clerk.headless*.js", "maxSize": "53KB" },
- { "path": "./dist/ui-common*.js", "maxSize": "107.5KB" },
+ { "path": "./dist/clerk.headless*.js", "maxSize": "53.06KB" },
+ { "path": "./dist/ui-common*.js", "maxSize": "108.35KB" },
  { "path": "./dist/vendors*.js", "maxSize": "40.2KB" },
  { "path": "./dist/coinbase*.js", "maxSize": "38KB" },
  { "path": "./dist/createorganization*.js", "maxSize": "5KB" },

packages/clerk-js/sandbox/app.ts

@@ -33,6 +33,7 @@ const AVAILABLE_COMPONENTS = [
  'organizationSwitcher',
  'waitlist',
  'pricingTable',
+ 'apiKeys',
  'oauthConsent',
 ] as const;
 
@@ -92,6 +93,7 @@ const componentControls: Record<(typeof AVAILABLE_COMPONENTS)[number], Component
  organizationSwitcher: buildComponentControls('organizationSwitcher'),
  waitlist: buildComponentControls('waitlist'),
  pricingTable: buildComponentControls('pricingTable'),
+ apiKeys: buildComponentControls('apiKeys'),
  oauthConsent: buildComponentControls('oauthConsent'),
 };
 
@@ -312,6 +314,9 @@ void (async () => {
  '/pricing-table': () => {
  Clerk.mountPricingTable(app, componentControls.pricingTable.getProps() ?? {});
  },
+ '/api-keys': () => {
+ Clerk.mountApiKeys(app, componentControls.apiKeys.getProps() ?? {});
+ },
  '/oauth-consent': () => {
  const searchParams = new URLSearchParams(window.location.search);
  const scopes = (searchParams.get('scopes')?.split(',') ?? []).map(scope => ({

packages/clerk-js/sandbox/template.html

@@ -260,6 +260,14 @@
  PricingTable
  </a>
  </li>
+ <li class="relative">
+ <a
+ class="relative isolate flex w-full rounded-md border border-white px-2 py-[0.4375rem] text-sm hover:bg-gray-50 aria-[current]:bg-gray-50"
+ href="/api-keys"
+ >
+ API Keys
+ </a>
+ </li>
  <li class="relative">
  <a
  class="relative isolate flex w-full rounded-md border border-white px-2 py-[0.4375rem] text-sm hover:bg-gray-50 aria-[current]:bg-gray-50"

packages/clerk-js/src/core/clerk.ts

@@ -20,6 +20,8 @@ import type {
  __internal_OAuthConsentProps,
  __internal_PlanDetailsProps,
  __internal_UserVerificationModalProps,
+ APIKeysNamespace,
+ APIKeysProps,
  AuthenticateWithCoinbaseWalletParams,
  AuthenticateWithGoogleOneTapParams,
  AuthenticateWithMetamaskParams,
@@ -88,6 +90,7 @@ import {
  createAllowedRedirectOrigins,
  createBeforeUnloadTracker,
  createPageLifecycle,
+ disabledAPIKeysFeature,
  disabledBillingFeature,
  disabledOrganizationsFeature,
  errorThrower,
@@ -132,6 +135,7 @@ import { eventBus, events } from './events';
 import type { FapiClient, FapiRequestCallback } from './fapiClient';
 import { createFapiClient } from './fapiClient';
 import { createClientFromJwt } from './jwt-client';
+import { APIKeys } from './modules/apiKeys';
 import { CommerceBilling } from './modules/commerce';
 import {
  BaseResource,
@@ -163,6 +167,7 @@ const CANNOT_RENDER_USER_MISSING_ERROR_CODE = 'cannot_render_user_missing';
 const CANNOT_RENDER_ORGANIZATIONS_DISABLED_ERROR_CODE = 'cannot_render_organizations_disabled';
 const CANNOT_RENDER_ORGANIZATION_MISSING_ERROR_CODE = 'cannot_render_organization_missing';
 const CANNOT_RENDER_SINGLE_SESSION_ENABLED_ERROR_CODE = 'cannot_render_single_session_enabled';
+const CANNOT_RENDER_API_KEYS_DISABLED_ERROR_CODE = 'cannot_render_api_keys_disabled';
 const defaultOptions: ClerkOptions = {
  polling: true,
  standardBrowser: true,
@@ -189,6 +194,7 @@ export class Clerk implements ClerkInterface {
  environment: process.env.NODE_ENV || 'production',
  };
  private static _billing: CommerceBillingNamespace;
+ private static _apiKeys: APIKeysNamespace;
 
  public client: ClientResource | undefined;
  public session: SignedInSessionResource | null | undefined;
@@ -324,6 +330,13 @@ export class Clerk implements ClerkInterface {
  return Clerk._billing;
  }
 
+ get apiKeys(): APIKeysNamespace {
+ if (!Clerk._apiKeys) {
+ Clerk._apiKeys = new APIKeys();
+ }
+ return Clerk._apiKeys;
+ }
+
  public __internal_getOption<K extends keyof ClerkOptions>(key: K): ClerkOptions[K] {
  return this.#options[key];
  }
@@ -1055,6 +1068,53 @@ export class Clerk implements ClerkInterface {
  void this.#componentControls.ensureMounted().then(controls => controls.unmountComponent({ node }));
  };
 
+ /**
+ * @experimental
+ * This API is in early access and may change in future releases.
+ *
+ * Mount a api keys component at the target element.
+ * @param targetNode Target to mount the APIKeys component.
+ * @param props Configuration parameters.
+ */
+ public mountApiKeys = (node: HTMLDivElement, props?: APIKeysProps) => {
+ this.assertComponentsReady(this.#componentControls);
+
+ logger.warnOnce('Clerk: <APIKeys /> component is in early access and not yet recommended for production use.');
+
+ if (disabledAPIKeysFeature(this, this.environment)) {
+ if (this.#instanceType === 'development') {
+ throw new ClerkRuntimeError(warnings.cannotRenderAPIKeysComponent, {
+ code: CANNOT_RENDER_API_KEYS_DISABLED_ERROR_CODE,
+ });
+ }
+ return;
+ }
+ void this.#componentControls.ensureMounted({ preloadHint: 'APIKeys' }).then(controls =>
+ controls.mountComponent({
+ name: 'APIKeys',
+ appearanceKey: 'apiKeys',
+ node,
+ props,
+ }),
+ );
+
+ this.telemetry?.record(eventPrebuiltComponentMounted('APIKeys', props));
+ };
+
+ /**
+ * @experimental
+ * This API is in early access and may change in future releases.
+ *
+ * Unmount a api keys component from the target element.
+ * If there is no component mounted at the target node, results in a noop.
+ *
+ * @param targetNode Target node to unmount the ApiKeys component from.
+ */
+ public unmountApiKeys = (node: HTMLDivElement) => {
+ this.assertComponentsReady(this.#componentControls);
+ void this.#componentControls.ensureMounted().then(controls => controls.unmountComponent({ node }));
+ };
+
  /**
  * `setActive` can be used to set the active session and/or organization.
  */

packages/clerk-js/src/core/fapiClient.ts

@@ -225,8 +225,8 @@ export function createFapiClient(options: FapiClientOptions): FapiClient {
  const urlStr = requestInit.url.toString();
  const fetchOpts: FapiRequestInit = {
  ...requestInit,
- credentials: 'include',
  method: overwrittenRequestMethod,
+ credentials: requestInit.credentials || 'include',
  };
 
  try {

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

@@ -0,0 +1,101 @@
+import type {
+ ApiKeyJSON,
+ APIKeyResource,
+ APIKeysNamespace,
+ CreateAPIKeyParams,
+ GetAPIKeysParams,
+ RevokeAPIKeyParams,
+} from '@clerk/types';
+
+import type { FapiRequestInit } from '@/core/fapiClient';
+
+import { APIKey, BaseResource, ClerkRuntimeError } from '../../resources/internal';
+
+export class APIKeys implements APIKeysNamespace {
+ /**
+ * Returns the base options for the FAPI proxy requests.
+ */
+ private async getBaseFapiProxyOptions(): Promise<FapiRequestInit> {
+ const token = await BaseResource.clerk.session?.getToken();
+ if (!token) {
+ throw new ClerkRuntimeError('No valid session token available', { code: 'no_session_token' });
+ }
+
+ return {
+ // Set to an empty string because FAPI Proxy does not include the version in the path.
+ pathPrefix: '',
+ // Set the session token as a Bearer token in the Authorization header for authentication.
+ headers: {
+ Authorization: `Bearer ${token}`,
+ 'Content-Type': 'application/json',
+ },
+ // Set to `same-origin` to ensure cookies and credentials are sent with requests, avoiding CORS issues.
+ credentials: 'same-origin',
+ };
+ }
+
+ 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 ?? '',
+ },
+ })
+ .then(res => {
+ const apiKeysJSON = res.payload as unknown as { api_keys: ApiKeyJSON[] };
+ return apiKeysJSON.api_keys.map(json => new APIKey(json));
+ });
+ }
+
+ async getSecret(id: string): Promise<string> {
+ return BaseResource.clerk
+ .getFapiClient()
+ .request<{ secret: string }>({
+ ...(await this.getBaseFapiProxyOptions()),
+ method: 'GET',
+ path: `/api_keys/${id}/secret`,
+ })
+ .then(res => {
+ const { secret } = res.payload as unknown as { secret: string };
+ return secret;
+ });
+ }
+
+ async create(params: CreateAPIKeyParams): Promise<APIKeyResource> {
+ const json = (
+ await BaseResource._fetch<ApiKeyJSON>({
+ ...(await this.getBaseFapiProxyOptions()),
+ path: '/api_keys',
+ method: 'POST',
+ body: JSON.stringify({
+ type: params.type ?? 'api_key',
+ name: params.name,
+ subject: params.subject ?? BaseResource.clerk.organization?.id ?? BaseResource.clerk.user?.id ?? '',
+ description: params.description,
+ seconds_until_expiration: params.secondsUntilExpiration,
+ }),
+ })
+ )?.response as ApiKeyJSON;
+
+ return new APIKey(json);
+ }
+
+ async revoke(params: RevokeAPIKeyParams): Promise<APIKeyResource> {
+ const json = (
+ await BaseResource._fetch<ApiKeyJSON>({
+ ...(await this.getBaseFapiProxyOptions()),
+ method: 'POST',
+ path: `/api_keys/${params.apiKeyID}/revoke`,
+ body: JSON.stringify({
+ revocation_reason: params.revocationReason,
+ }),
+ })
+ )?.response as ApiKeyJSON;
+
+ return new APIKey(json);
+ }
+}

packages/clerk-js/src/core/resources/APIKey.ts

@@ -0,0 +1,73 @@
+import type { ApiKeyJSON, APIKeyResource } from '@clerk/types';
+
+import { unixEpochToDate } from '../../utils/date';
+import { BaseResource } from './internal';
+
+export class APIKey extends BaseResource implements APIKeyResource {
+ pathRoot = '/api_keys';
+
+ id!: string;
+ type!: string;
+ name!: string;
+ subject!: string;
+ scopes!: string[];
+ claims!: Record<string, any> | null;
+ revoked!: boolean;
+ revocationReason!: string | null;
+ expired!: boolean;
+ expiration!: Date | null;
+ createdBy!: string | null;
+ description!: string | null;
+ lastUsedAt!: Date | null;
+ createdAt!: Date;
+ updatedAt!: Date;
+
+ constructor(data: ApiKeyJSON) {
+ super();
+ this.fromJSON(data);
+ }
+
+ protected fromJSON(data: ApiKeyJSON | null): this {
+ if (!data) {
+ return this;
+ }
+
+ this.id = data.id;
+ this.type = data.type;
+ this.name = data.name;
+ this.subject = data.subject;
+ this.scopes = data.scopes;
+ this.claims = data.claims;
+ this.revoked = data.revoked;
+ this.revocationReason = data.revocation_reason;
+ this.expired = data.expired;
+ this.expiration = data.expiration ? unixEpochToDate(data.expiration) : null;
+ this.createdBy = data.created_by;
+ this.description = data.description;
+ this.lastUsedAt = data.last_used_at ? unixEpochToDate(data.last_used_at) : null;
+ this.updatedAt = unixEpochToDate(data.updated_at);
+ this.createdAt = unixEpochToDate(data.created_at);
+ return this;
+ }
+
+ public __internal_toSnapshot(): ApiKeyJSON {
+ return {
+ object: 'api_key',
+ id: this.id,
+ type: this.type,
+ name: this.name,
+ subject: this.subject,
+ scopes: this.scopes,
+ claims: this.claims,
+ revoked: this.revoked,
+ revocation_reason: this.revocationReason,
+ expired: this.expired,
+ expiration: this.expiration ? this.expiration.getTime() : null,
+ created_by: this.createdBy,
+ description: this.description,
+ last_used_at: this.lastUsedAt ? this.lastUsedAt.getTime() : null,
+ created_at: this.createdAt.getTime(),
+ updated_at: this.updatedAt.getTime(),
+ };
+ }
+}

.changeset/fluffy-numbers-stick.md

@@ -0,0 +1,6 @@
+---
+'@clerk/localizations': patch
+'@clerk/types': patch
+---
+
+Add TypeScript types and en-US localization for upcoming `<APIKeys />` component. This component will initially be in early access.

.changeset/ninety-candles-sleep.md

@@ -0,0 +1,7 @@
+---
+'@clerk/clerk-js': minor
+'@clerk/nextjs': minor
+'@clerk/clerk-react': minor
+---
+
+Add `<APIKeys />` component. This component will initially be in early access and not recommended for production usage just yet.

.typedoc/__tests__/__snapshots__/file-structure.test.ts.snap

@@ -129,6 +129,7 @@ exports[`Typedoc output > should have a deliberate file structure 1`] = `
  "nextjs/create-sync-get-auth.mdx",
  "nextjs/current-user.mdx",
  "nextjs/get-auth.mdx",
+ "clerk-react/api-keys.mdx",
  "clerk-react/clerk-provider-props.mdx",
  "clerk-react/protect.mdx",
  "clerk-react/redirect-to-create-organization.mdx",

packages/chrome-extension/src/__tests__/__snapshots__/exports.test.ts.snap

@@ -2,6 +2,7 @@
 
 exports[`public exports should not include a breaking change 1`] = `
 [
+ "APIKeys",
  "AuthenticateWithRedirectCallback",
  "ClerkDegraded",
  "ClerkFailed",

packages/clerk-js/bundlewatch.config.json

@@ -1,10 +1,10 @@
 {
  "files": [
- { "path": "./dist/clerk.js", "maxSize": "605kB" },
- { "path": "./dist/clerk.browser.js", "maxSize": "69.3KB" },
+ { "path": "./dist/clerk.js", "maxSize": "608.89kB" },
+ { "path": "./dist/clerk.browser.js", "maxSize": "70.15KB" },
  { "path": "./dist/clerk.legacy.browser.js", "maxSize": "113KB" },
- { "path": "./dist/clerk.headless*.js", "maxSize": "53KB" },
- { "path": "./dist/ui-common*.js", "maxSize": "107.5KB" },
+ { "path": "./dist/clerk.headless*.js", "maxSize": "53.06KB" },
+ { "path": "./dist/ui-common*.js", "maxSize": "108.35KB" },
  { "path": "./dist/vendors*.js", "maxSize": "40.2KB" },
  { "path": "./dist/coinbase*.js", "maxSize": "38KB" },
  { "path": "./dist/createorganization*.js", "maxSize": "5KB" },

packages/clerk-js/sandbox/app.ts

@@ -33,6 +33,7 @@ const AVAILABLE_COMPONENTS = [
  'organizationSwitcher',
  'waitlist',
  'pricingTable',
+ 'apiKeys',
  'oauthConsent',
 ] as const;
 
@@ -92,6 +93,7 @@ const componentControls: Record<(typeof AVAILABLE_COMPONENTS)[number], Component
  organizationSwitcher: buildComponentControls('organizationSwitcher'),
  waitlist: buildComponentControls('waitlist'),
  pricingTable: buildComponentControls('pricingTable'),
+ apiKeys: buildComponentControls('apiKeys'),
  oauthConsent: buildComponentControls('oauthConsent'),
 };
 
@@ -312,6 +314,9 @@ void (async () => {
  '/pricing-table': () => {
  Clerk.mountPricingTable(app, componentControls.pricingTable.getProps() ?? {});
  },
+ '/api-keys': () => {
+ Clerk.mountApiKeys(app, componentControls.apiKeys.getProps() ?? {});
+ },
  '/oauth-consent': () => {
  const searchParams = new URLSearchParams(window.location.search);
  const scopes = (searchParams.get('scopes')?.split(',') ?? []).map(scope => ({

packages/clerk-js/sandbox/template.html

@@ -260,6 +260,14 @@
  PricingTable
  </a>
  </li>
+ <li class="relative">
+ <a
+ class="relative isolate flex w-full rounded-md border border-white px-2 py-[0.4375rem] text-sm hover:bg-gray-50 aria-[current]:bg-gray-50"
+ href="/api-keys"
+ >
+ API Keys
+ </a>
+ </li>
  <li class="relative">
  <a
  class="relative isolate flex w-full rounded-md border border-white px-2 py-[0.4375rem] text-sm hover:bg-gray-50 aria-[current]:bg-gray-50"

packages/clerk-js/src/core/clerk.ts

@@ -20,6 +20,8 @@ import type {
  __internal_OAuthConsentProps,
  __internal_PlanDetailsProps,
  __internal_UserVerificationModalProps,
+ APIKeysNamespace,
+ APIKeysProps,
  AuthenticateWithCoinbaseWalletParams,
  AuthenticateWithGoogleOneTapParams,
  AuthenticateWithMetamaskParams,
@@ -88,6 +90,7 @@ import {
  createAllowedRedirectOrigins,
  createBeforeUnloadTracker,
  createPageLifecycle,
+ disabledAPIKeysFeature,
  disabledBillingFeature,
  disabledOrganizationsFeature,
  errorThrower,
@@ -132,6 +135,7 @@ import { eventBus, events } from './events';
 import type { FapiClient, FapiRequestCallback } from './fapiClient';
 import { createFapiClient } from './fapiClient';
 import { createClientFromJwt } from './jwt-client';
+import { APIKeys } from './modules/apiKeys';
 import { CommerceBilling } from './modules/commerce';
 import {
  BaseResource,
@@ -163,6 +167,7 @@ const CANNOT_RENDER_USER_MISSING_ERROR_CODE = 'cannot_render_user_missing';
 const CANNOT_RENDER_ORGANIZATIONS_DISABLED_ERROR_CODE = 'cannot_render_organizations_disabled';
 const CANNOT_RENDER_ORGANIZATION_MISSING_ERROR_CODE = 'cannot_render_organization_missing';
 const CANNOT_RENDER_SINGLE_SESSION_ENABLED_ERROR_CODE = 'cannot_render_single_session_enabled';
+const CANNOT_RENDER_API_KEYS_DISABLED_ERROR_CODE = 'cannot_render_api_keys_disabled';
 const defaultOptions: ClerkOptions = {
  polling: true,
  standardBrowser: true,
@@ -189,6 +194,7 @@ export class Clerk implements ClerkInterface {
  environment: process.env.NODE_ENV || 'production',
  };
  private static _billing: CommerceBillingNamespace;
+ private static _apiKeys: APIKeysNamespace;
 
  public client: ClientResource | undefined;
  public session: SignedInSessionResource | null | undefined;
@@ -324,6 +330,13 @@ export class Clerk implements ClerkInterface {
  return Clerk._billing;
  }
 
+ get apiKeys(): APIKeysNamespace {
+ if (!Clerk._apiKeys) {
+ Clerk._apiKeys = new APIKeys();
+ }
+ return Clerk._apiKeys;
+ }
+
  public __internal_getOption<K extends keyof ClerkOptions>(key: K): ClerkOptions[K] {
  return this.#options[key];
  }
@@ -1055,6 +1068,53 @@ export class Clerk implements ClerkInterface {
  void this.#componentControls.ensureMounted().then(controls => controls.unmountComponent({ node }));
  };
 
+ /**
+ * @experimental
+ * This API is in early access and may change in future releases.
+ *
+ * Mount a api keys component at the target element.
+ * @param targetNode Target to mount the APIKeys component.
+ * @param props Configuration parameters.
+ */
+ public mountApiKeys = (node: HTMLDivElement, props?: APIKeysProps) => {
+ this.assertComponentsReady(this.#componentControls);
+
+ logger.warnOnce('Clerk: <APIKeys /> component is in early access and not yet recommended for production use.');
+
+ if (disabledAPIKeysFeature(this, this.environment)) {
+ if (this.#instanceType === 'development') {
+ throw new ClerkRuntimeError(warnings.cannotRenderAPIKeysComponent, {
+ code: CANNOT_RENDER_API_KEYS_DISABLED_ERROR_CODE,
+ });
+ }
+ return;
+ }
+ void this.#componentControls.ensureMounted({ preloadHint: 'APIKeys' }).then(controls =>
+ controls.mountComponent({
+ name: 'APIKeys',
+ appearanceKey: 'apiKeys',
+ node,
+ props,
+ }),
+ );
+
+ this.telemetry?.record(eventPrebuiltComponentMounted('APIKeys', props));
+ };
+
+ /**
+ * @experimental
+ * This API is in early access and may change in future releases.
+ *
+ * Unmount a api keys component from the target element.
+ * If there is no component mounted at the target node, results in a noop.
+ *
+ * @param targetNode Target node to unmount the ApiKeys component from.
+ */
+ public unmountApiKeys = (node: HTMLDivElement) => {
+ this.assertComponentsReady(this.#componentControls);
+ void this.#componentControls.ensureMounted().then(controls => controls.unmountComponent({ node }));
+ };
+
  /**
  * `setActive` can be used to set the active session and/or organization.
  */

packages/clerk-js/src/core/fapiClient.ts

@@ -225,8 +225,8 @@ export function createFapiClient(options: FapiClientOptions): FapiClient {
  const urlStr = requestInit.url.toString();
  const fetchOpts: FapiRequestInit = {
  ...requestInit,
- credentials: 'include',
  method: overwrittenRequestMethod,
+ credentials: requestInit.credentials || 'include',
  };
 
  try {

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

@@ -0,0 +1,101 @@
+import type {
+ ApiKeyJSON,
+ APIKeyResource,
+ APIKeysNamespace,
+ CreateAPIKeyParams,
+ GetAPIKeysParams,
+ RevokeAPIKeyParams,
+} from '@clerk/types';
+
+import type { FapiRequestInit } from '@/core/fapiClient';
+
+import { APIKey, BaseResource, ClerkRuntimeError } from '../../resources/internal';
+
+export class APIKeys implements APIKeysNamespace {
+ /**
+ * Returns the base options for the FAPI proxy requests.
+ */
+ private async getBaseFapiProxyOptions(): Promise<FapiRequestInit> {
+ const token = await BaseResource.clerk.session?.getToken();
+ if (!token) {
+ throw new ClerkRuntimeError('No valid session token available', { code: 'no_session_token' });
+ }
+
+ return {
+ // Set to an empty string because FAPI Proxy does not include the version in the path.
+ pathPrefix: '',
+ // Set the session token as a Bearer token in the Authorization header for authentication.
+ headers: {
+ Authorization: `Bearer ${token}`,
+ 'Content-Type': 'application/json',
+ },
+ // Set to `same-origin` to ensure cookies and credentials are sent with requests, avoiding CORS issues.
+ credentials: 'same-origin',
+ };
+ }
+
+ 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 ?? '',
+ },
+ })
+ .then(res => {
+ const apiKeysJSON = res.payload as unknown as { api_keys: ApiKeyJSON[] };
+ return apiKeysJSON.api_keys.map(json => new APIKey(json));
+ });
+ }
+
+ async getSecret(id: string): Promise<string> {
+ return BaseResource.clerk
+ .getFapiClient()
+ .request<{ secret: string }>({
+ ...(await this.getBaseFapiProxyOptions()),
+ method: 'GET',
+ path: `/api_keys/${id}/secret`,
+ })
+ .then(res => {
+ const { secret } = res.payload as unknown as { secret: string };
+ return secret;
+ });
+ }
+
+ async create(params: CreateAPIKeyParams): Promise<APIKeyResource> {
+ const json = (
+ await BaseResource._fetch<ApiKeyJSON>({
+ ...(await this.getBaseFapiProxyOptions()),
+ path: '/api_keys',
+ method: 'POST',
+ body: JSON.stringify({
+ type: params.type ?? 'api_key',
+ name: params.name,
+ subject: params.subject ?? BaseResource.clerk.organization?.id ?? BaseResource.clerk.user?.id ?? '',
+ description: params.description,
+ seconds_until_expiration: params.secondsUntilExpiration,
+ }),
+ })
+ )?.response as ApiKeyJSON;
+
+ return new APIKey(json);
+ }
+
+ async revoke(params: RevokeAPIKeyParams): Promise<APIKeyResource> {
+ const json = (
+ await BaseResource._fetch<ApiKeyJSON>({
+ ...(await this.getBaseFapiProxyOptions()),
+ method: 'POST',
+ path: `/api_keys/${params.apiKeyID}/revoke`,
+ body: JSON.stringify({
+ revocation_reason: params.revocationReason,
+ }),
+ })
+ )?.response as ApiKeyJSON;
+
+ return new APIKey(json);
+ }
+}

packages/clerk-js/src/core/resources/APIKey.ts

@@ -0,0 +1,73 @@
+import type { ApiKeyJSON, APIKeyResource } from '@clerk/types';
+
+import { unixEpochToDate } from '../../utils/date';
+import { BaseResource } from './internal';
+
+export class APIKey extends BaseResource implements APIKeyResource {
+ pathRoot = '/api_keys';
+
+ id!: string;
+ type!: string;
+ name!: string;
+ subject!: string;
+ scopes!: string[];
+ claims!: Record<string, any> | null;
+ revoked!: boolean;
+ revocationReason!: string | null;
+ expired!: boolean;
+ expiration!: Date | null;
+ createdBy!: string | null;
+ description!: string | null;
+ lastUsedAt!: Date | null;
+ createdAt!: Date;
+ updatedAt!: Date;
+
+ constructor(data: ApiKeyJSON) {
+ super();
+ this.fromJSON(data);
+ }
+
+ protected fromJSON(data: ApiKeyJSON | null): this {
+ if (!data) {
+ return this;
+ }
+
+ this.id = data.id;
+ this.type = data.type;
+ this.name = data.name;
+ this.subject = data.subject;
+ this.scopes = data.scopes;
+ this.claims = data.claims;
+ this.revoked = data.revoked;
+ this.revocationReason = data.revocation_reason;
+ this.expired = data.expired;
+ this.expiration = data.expiration ? unixEpochToDate(data.expiration) : null;
+ this.createdBy = data.created_by;
+ this.description = data.description;
+ this.lastUsedAt = data.last_used_at ? unixEpochToDate(data.last_used_at) : null;
+ this.updatedAt = unixEpochToDate(data.updated_at);
+ this.createdAt = unixEpochToDate(data.created_at);
+ return this;
+ }
+
+ public __internal_toSnapshot(): ApiKeyJSON {
+ return {
+ object: 'api_key',
+ id: this.id,
+ type: this.type,
+ name: this.name,
+ subject: this.subject,
+ scopes: this.scopes,
+ claims: this.claims,
+ revoked: this.revoked,
+ revocation_reason: this.revocationReason,
+ expired: this.expired,
+ expiration: this.expiration ? this.expiration.getTime() : null,
+ created_by: this.createdBy,
+ description: this.description,
+ last_used_at: this.lastUsedAt ? this.lastUsedAt.getTime() : null,
+ created_at: this.createdAt.getTime(),
+ updated_at: this.updatedAt.getTime(),
+ };
+ }
+}

.changeset/fluffy-numbers-stick.md

@@ -0,0 +1,6 @@
+---
+'@clerk/localizations': patch
+'@clerk/types': patch
+---
+
+Add TypeScript types and en-US localization for upcoming `<APIKeys />` component. This component will initially be in early access.

.changeset/ninety-candles-sleep.md

@@ -0,0 +1,7 @@
+---
+'@clerk/clerk-js': minor
+'@clerk/nextjs': minor
+'@clerk/clerk-react': minor
+---
+
+Add `<APIKeys />` component. This component will initially be in early access and not recommended for production usage just yet.

.typedoc/__tests__/__snapshots__/file-structure.test.ts.snap

@@ -129,6 +129,7 @@ exports[`Typedoc output > should have a deliberate file structure 1`] = `
  "nextjs/create-sync-get-auth.mdx",
  "nextjs/current-user.mdx",
  "nextjs/get-auth.mdx",
+ "clerk-react/api-keys.mdx",
  "clerk-react/clerk-provider-props.mdx",
  "clerk-react/protect.mdx",
  "clerk-react/redirect-to-create-organization.mdx",

packages/chrome-extension/src/__tests__/__snapshots__/exports.test.ts.snap

@@ -2,6 +2,7 @@
 
 exports[`public exports should not include a breaking change 1`] = `
 [
+ "APIKeys",
  "AuthenticateWithRedirectCallback",
  "ClerkDegraded",
  "ClerkFailed",

packages/clerk-js/bundlewatch.config.json

@@ -1,10 +1,10 @@
 {
  "files": [
- { "path": "./dist/clerk.js", "maxSize": "605kB" },
- { "path": "./dist/clerk.browser.js", "maxSize": "69.3KB" },
+ { "path": "./dist/clerk.js", "maxSize": "608.89kB" },
+ { "path": "./dist/clerk.browser.js", "maxSize": "70.15KB" },
  { "path": "./dist/clerk.legacy.browser.js", "maxSize": "113KB" },
- { "path": "./dist/clerk.headless*.js", "maxSize": "53KB" },
- { "path": "./dist/ui-common*.js", "maxSize": "107.5KB" },
+ { "path": "./dist/clerk.headless*.js", "maxSize": "53.06KB" },
+ { "path": "./dist/ui-common*.js", "maxSize": "108.35KB" },
  { "path": "./dist/vendors*.js", "maxSize": "40.2KB" },
  { "path": "./dist/coinbase*.js", "maxSize": "38KB" },
  { "path": "./dist/createorganization*.js", "maxSize": "5KB" },

packages/clerk-js/sandbox/app.ts

@@ -33,6 +33,7 @@ const AVAILABLE_COMPONENTS = [
  'organizationSwitcher',
  'waitlist',
  'pricingTable',
+ 'apiKeys',
  'oauthConsent',
 ] as const;
 
@@ -92,6 +93,7 @@ const componentControls: Record<(typeof AVAILABLE_COMPONENTS)[number], Component
  organizationSwitcher: buildComponentControls('organizationSwitcher'),
  waitlist: buildComponentControls('waitlist'),
  pricingTable: buildComponentControls('pricingTable'),
+ apiKeys: buildComponentControls('apiKeys'),
  oauthConsent: buildComponentControls('oauthConsent'),
 };
 
@@ -312,6 +314,9 @@ void (async () => {
  '/pricing-table': () => {
  Clerk.mountPricingTable(app, componentControls.pricingTable.getProps() ?? {});
  },
+ '/api-keys': () => {
+ Clerk.mountApiKeys(app, componentControls.apiKeys.getProps() ?? {});
+ },
  '/oauth-consent': () => {
  const searchParams = new URLSearchParams(window.location.search);
  const scopes = (searchParams.get('scopes')?.split(',') ?? []).map(scope => ({

packages/clerk-js/sandbox/template.html

@@ -260,6 +260,14 @@
  PricingTable
  </a>
  </li>
+ <li class="relative">
+ <a
+ class="relative isolate flex w-full rounded-md border border-white px-2 py-[0.4375rem] text-sm hover:bg-gray-50 aria-[current]:bg-gray-50"
+ href="/api-keys"
+ >
+ API Keys
+ </a>
+ </li>
  <li class="relative">
  <a
  class="relative isolate flex w-full rounded-md border border-white px-2 py-[0.4375rem] text-sm hover:bg-gray-50 aria-[current]:bg-gray-50"

packages/clerk-js/src/core/clerk.ts

@@ -20,6 +20,8 @@ import type {
  __internal_OAuthConsentProps,
  __internal_PlanDetailsProps,
  __internal_UserVerificationModalProps,
+ APIKeysNamespace,
+ APIKeysProps,
  AuthenticateWithCoinbaseWalletParams,
  AuthenticateWithGoogleOneTapParams,
  AuthenticateWithMetamaskParams,
@@ -88,6 +90,7 @@ import {
  createAllowedRedirectOrigins,
  createBeforeUnloadTracker,
  createPageLifecycle,
+ disabledAPIKeysFeature,
  disabledBillingFeature,
  disabledOrganizationsFeature,
  errorThrower,
@@ -132,6 +135,7 @@ import { eventBus, events } from './events';
 import type { FapiClient, FapiRequestCallback } from './fapiClient';
 import { createFapiClient } from './fapiClient';
 import { createClientFromJwt } from './jwt-client';
+import { APIKeys } from './modules/apiKeys';
 import { CommerceBilling } from './modules/commerce';
 import {
  BaseResource,
@@ -163,6 +167,7 @@ const CANNOT_RENDER_USER_MISSING_ERROR_CODE = 'cannot_render_user_missing';
 const CANNOT_RENDER_ORGANIZATIONS_DISABLED_ERROR_CODE = 'cannot_render_organizations_disabled';
 const CANNOT_RENDER_ORGANIZATION_MISSING_ERROR_CODE = 'cannot_render_organization_missing';
 const CANNOT_RENDER_SINGLE_SESSION_ENABLED_ERROR_CODE = 'cannot_render_single_session_enabled';
+const CANNOT_RENDER_API_KEYS_DISABLED_ERROR_CODE = 'cannot_render_api_keys_disabled';
 const defaultOptions: ClerkOptions = {
  polling: true,
  standardBrowser: true,
@@ -189,6 +194,7 @@ export class Clerk implements ClerkInterface {
  environment: process.env.NODE_ENV || 'production',
  };
  private static _billing: CommerceBillingNamespace;
+ private static _apiKeys: APIKeysNamespace;
 
  public client: ClientResource | undefined;
  public session: SignedInSessionResource | null | undefined;
@@ -324,6 +330,13 @@ export class Clerk implements ClerkInterface {
  return Clerk._billing;
  }
 
+ get apiKeys(): APIKeysNamespace {
+ if (!Clerk._apiKeys) {
+ Clerk._apiKeys = new APIKeys();
+ }
+ return Clerk._apiKeys;
+ }
+
  public __internal_getOption<K extends keyof ClerkOptions>(key: K): ClerkOptions[K] {
  return this.#options[key];
  }
@@ -1055,6 +1068,53 @@ export class Clerk implements ClerkInterface {
  void this.#componentControls.ensureMounted().then(controls => controls.unmountComponent({ node }));
  };
 
+ /**
+ * @experimental
+ * This API is in early access and may change in future releases.
+ *
+ * Mount a api keys component at the target element.
+ * @param targetNode Target to mount the APIKeys component.
+ * @param props Configuration parameters.
+ */
+ public mountApiKeys = (node: HTMLDivElement, props?: APIKeysProps) => {
+ this.assertComponentsReady(this.#componentControls);
+
+ logger.warnOnce('Clerk: <APIKeys /> component is in early access and not yet recommended for production use.');
+
+ if (disabledAPIKeysFeature(this, this.environment)) {
+ if (this.#instanceType === 'development') {
+ throw new ClerkRuntimeError(warnings.cannotRenderAPIKeysComponent, {
+ code: CANNOT_RENDER_API_KEYS_DISABLED_ERROR_CODE,
+ });
+ }
+ return;
+ }
+ void this.#componentControls.ensureMounted({ preloadHint: 'APIKeys' }).then(controls =>
+ controls.mountComponent({
+ name: 'APIKeys',
+ appearanceKey: 'apiKeys',
+ node,
+ props,
+ }),
+ );
+
+ this.telemetry?.record(eventPrebuiltComponentMounted('APIKeys', props));
+ };
+
+ /**
+ * @experimental
+ * This API is in early access and may change in future releases.
+ *
+ * Unmount a api keys component from the target element.
+ * If there is no component mounted at the target node, results in a noop.
+ *
+ * @param targetNode Target node to unmount the ApiKeys component from.
+ */
+ public unmountApiKeys = (node: HTMLDivElement) => {
+ this.assertComponentsReady(this.#componentControls);
+ void this.#componentControls.ensureMounted().then(controls => controls.unmountComponent({ node }));
+ };
+
  /**
  * `setActive` can be used to set the active session and/or organization.
  */

packages/clerk-js/src/core/fapiClient.ts

@@ -225,8 +225,8 @@ export function createFapiClient(options: FapiClientOptions): FapiClient {
  const urlStr = requestInit.url.toString();
  const fetchOpts: FapiRequestInit = {
  ...requestInit,
- credentials: 'include',
  method: overwrittenRequestMethod,
+ credentials: requestInit.credentials || 'include',
  };
 
  try {

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

@@ -0,0 +1,101 @@
+import type {
+ ApiKeyJSON,
+ APIKeyResource,
+ APIKeysNamespace,
+ CreateAPIKeyParams,
+ GetAPIKeysParams,
+ RevokeAPIKeyParams,
+} from '@clerk/types';
+
+import type { FapiRequestInit } from '@/core/fapiClient';
+
+import { APIKey, BaseResource, ClerkRuntimeError } from '../../resources/internal';
+
+export class APIKeys implements APIKeysNamespace {
+ /**
+ * Returns the base options for the FAPI proxy requests.
+ */
+ private async getBaseFapiProxyOptions(): Promise<FapiRequestInit> {
+ const token = await BaseResource.clerk.session?.getToken();
+ if (!token) {
+ throw new ClerkRuntimeError('No valid session token available', { code: 'no_session_token' });
+ }
+
+ return {
+ // Set to an empty string because FAPI Proxy does not include the version in the path.
+ pathPrefix: '',
+ // Set the session token as a Bearer token in the Authorization header for authentication.
+ headers: {
+ Authorization: `Bearer ${token}`,
+ 'Content-Type': 'application/json',
+ },
+ // Set to `same-origin` to ensure cookies and credentials are sent with requests, avoiding CORS issues.
+ credentials: 'same-origin',
+ };
+ }
+
+ 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 ?? '',
+ },
+ })
+ .then(res => {
+ const apiKeysJSON = res.payload as unknown as { api_keys: ApiKeyJSON[] };
+ return apiKeysJSON.api_keys.map(json => new APIKey(json));
+ });
+ }
+
+ async getSecret(id: string): Promise<string> {
+ return BaseResource.clerk
+ .getFapiClient()
+ .request<{ secret: string }>({
+ ...(await this.getBaseFapiProxyOptions()),
+ method: 'GET',
+ path: `/api_keys/${id}/secret`,
+ })
+ .then(res => {
+ const { secret } = res.payload as unknown as { secret: string };
+ return secret;
+ });
+ }
+
+ async create(params: CreateAPIKeyParams): Promise<APIKeyResource> {
+ const json = (
+ await BaseResource._fetch<ApiKeyJSON>({
+ ...(await this.getBaseFapiProxyOptions()),
+ path: '/api_keys',
+ method: 'POST',
+ body: JSON.stringify({
+ type: params.type ?? 'api_key',
+ name: params.name,
+ subject: params.subject ?? BaseResource.clerk.organization?.id ?? BaseResource.clerk.user?.id ?? '',
+ description: params.description,
+ seconds_until_expiration: params.secondsUntilExpiration,
+ }),
+ })
+ )?.response as ApiKeyJSON;
+
+ return new APIKey(json);
+ }
+
+ async revoke(params: RevokeAPIKeyParams): Promise<APIKeyResource> {
+ const json = (
+ await BaseResource._fetch<ApiKeyJSON>({
+ ...(await this.getBaseFapiProxyOptions()),
+ method: 'POST',
+ path: `/api_keys/${params.apiKeyID}/revoke`,
+ body: JSON.stringify({
+ revocation_reason: params.revocationReason,
+ }),
+ })
+ )?.response as ApiKeyJSON;
+
+ return new APIKey(json);
+ }
+}

packages/clerk-js/src/core/resources/APIKey.ts

@@ -0,0 +1,73 @@
+import type { ApiKeyJSON, APIKeyResource } from '@clerk/types';
+
+import { unixEpochToDate } from '../../utils/date';
+import { BaseResource } from './internal';
+
+export class APIKey extends BaseResource implements APIKeyResource {
+ pathRoot = '/api_keys';
+
+ id!: string;
+ type!: string;
+ name!: string;
+ subject!: string;
+ scopes!: string[];
+ claims!: Record<string, any> | null;
+ revoked!: boolean;
+ revocationReason!: string | null;
+ expired!: boolean;
+ expiration!: Date | null;
+ createdBy!: string | null;
+ description!: string | null;
+ lastUsedAt!: Date | null;
+ createdAt!: Date;
+ updatedAt!: Date;
+
+ constructor(data: ApiKeyJSON) {
+ super();
+ this.fromJSON(data);
+ }
+
+ protected fromJSON(data: ApiKeyJSON | null): this {
+ if (!data) {
+ return this;
+ }
+
+ this.id = data.id;
+ this.type = data.type;
+ this.name = data.name;
+ this.subject = data.subject;
+ this.scopes = data.scopes;
+ this.claims = data.claims;
+ this.revoked = data.revoked;
+ this.revocationReason = data.revocation_reason;
+ this.expired = data.expired;
+ this.expiration = data.expiration ? unixEpochToDate(data.expiration) : null;
+ this.createdBy = data.created_by;
+ this.description = data.description;
+ this.lastUsedAt = data.last_used_at ? unixEpochToDate(data.last_used_at) : null;
+ this.updatedAt = unixEpochToDate(data.updated_at);
+ this.createdAt = unixEpochToDate(data.created_at);
+ return this;
+ }
+
+ public __internal_toSnapshot(): ApiKeyJSON {
+ return {
+ object: 'api_key',
+ id: this.id,
+ type: this.type,
+ name: this.name,
+ subject: this.subject,
+ scopes: this.scopes,
+ claims: this.claims,
+ revoked: this.revoked,
+ revocation_reason: this.revocationReason,
+ expired: this.expired,
+ expiration: this.expiration ? this.expiration.getTime() : null,
+ created_by: this.createdBy,
+ description: this.description,
+ last_used_at: this.lastUsedAt ? this.lastUsedAt.getTime() : null,
+ created_at: this.createdAt.getTime(),
+ updated_at: this.updatedAt.getTime(),
+ };
+ }
+}

.changeset/fluffy-numbers-stick.md

@@ -0,0 +1,6 @@
+---
+'@clerk/localizations': patch
+'@clerk/types': patch
+---
+
+Add TypeScript types and en-US localization for upcoming `<APIKeys />` component. This component will initially be in early access.

.changeset/ninety-candles-sleep.md

@@ -0,0 +1,7 @@
+---
+'@clerk/clerk-js': minor
+'@clerk/nextjs': minor
+'@clerk/clerk-react': minor
+---
+
+Add `<APIKeys />` component. This component will initially be in early access and not recommended for production usage just yet.

.typedoc/__tests__/__snapshots__/file-structure.test.ts.snap

@@ -129,6 +129,7 @@ exports[`Typedoc output > should have a deliberate file structure 1`] = `
  "nextjs/create-sync-get-auth.mdx",
  "nextjs/current-user.mdx",
  "nextjs/get-auth.mdx",
+ "clerk-react/api-keys.mdx",
  "clerk-react/clerk-provider-props.mdx",
  "clerk-react/protect.mdx",
  "clerk-react/redirect-to-create-organization.mdx",

packages/chrome-extension/src/__tests__/__snapshots__/exports.test.ts.snap

@@ -2,6 +2,7 @@
 
 exports[`public exports should not include a breaking change 1`] = `
 [
+ "APIKeys",
  "AuthenticateWithRedirectCallback",
  "ClerkDegraded",
  "ClerkFailed",

packages/clerk-js/bundlewatch.config.json

@@ -1,10 +1,10 @@
 {
  "files": [
- { "path": "./dist/clerk.js", "maxSize": "605kB" },
- { "path": "./dist/clerk.browser.js", "maxSize": "69.3KB" },
+ { "path": "./dist/clerk.js", "maxSize": "608.89kB" },
+ { "path": "./dist/clerk.browser.js", "maxSize": "70.15KB" },
  { "path": "./dist/clerk.legacy.browser.js", "maxSize": "113KB" },
- { "path": "./dist/clerk.headless*.js", "maxSize": "53KB" },
- { "path": "./dist/ui-common*.js", "maxSize": "107.5KB" },
+ { "path": "./dist/clerk.headless*.js", "maxSize": "53.06KB" },
+ { "path": "./dist/ui-common*.js", "maxSize": "108.35KB" },
  { "path": "./dist/vendors*.js", "maxSize": "40.2KB" },
  { "path": "./dist/coinbase*.js", "maxSize": "38KB" },
  { "path": "./dist/createorganization*.js", "maxSize": "5KB" },

packages/clerk-js/sandbox/app.ts

@@ -33,6 +33,7 @@ const AVAILABLE_COMPONENTS = [
  'organizationSwitcher',
  'waitlist',
  'pricingTable',
+ 'apiKeys',
  'oauthConsent',
 ] as const;
 
@@ -92,6 +93,7 @@ const componentControls: Record<(typeof AVAILABLE_COMPONENTS)[number], Component
  organizationSwitcher: buildComponentControls('organizationSwitcher'),
  waitlist: buildComponentControls('waitlist'),
  pricingTable: buildComponentControls('pricingTable'),
+ apiKeys: buildComponentControls('apiKeys'),
  oauthConsent: buildComponentControls('oauthConsent'),
 };
 
@@ -312,6 +314,9 @@ void (async () => {
  '/pricing-table': () => {
  Clerk.mountPricingTable(app, componentControls.pricingTable.getProps() ?? {});
  },
+ '/api-keys': () => {
+ Clerk.mountApiKeys(app, componentControls.apiKeys.getProps() ?? {});
+ },
  '/oauth-consent': () => {
  const searchParams = new URLSearchParams(window.location.search);
  const scopes = (searchParams.get('scopes')?.split(',') ?? []).map(scope => ({

packages/clerk-js/sandbox/template.html

@@ -260,6 +260,14 @@
  PricingTable
  </a>
  </li>
+ <li class="relative">
+ <a
+ class="relative isolate flex w-full rounded-md border border-white px-2 py-[0.4375rem] text-sm hover:bg-gray-50 aria-[current]:bg-gray-50"
+ href="/api-keys"
+ >
+ API Keys
+ </a>
+ </li>
  <li class="relative">
  <a
  class="relative isolate flex w-full rounded-md border border-white px-2 py-[0.4375rem] text-sm hover:bg-gray-50 aria-[current]:bg-gray-50"

packages/clerk-js/src/core/clerk.ts

@@ -20,6 +20,8 @@ import type {
  __internal_OAuthConsentProps,
  __internal_PlanDetailsProps,
  __internal_UserVerificationModalProps,
+ APIKeysNamespace,
+ APIKeysProps,
  AuthenticateWithCoinbaseWalletParams,
  AuthenticateWithGoogleOneTapParams,
  AuthenticateWithMetamaskParams,
@@ -88,6 +90,7 @@ import {
  createAllowedRedirectOrigins,
  createBeforeUnloadTracker,
  createPageLifecycle,
+ disabledAPIKeysFeature,
  disabledBillingFeature,
  disabledOrganizationsFeature,
  errorThrower,
@@ -132,6 +135,7 @@ import { eventBus, events } from './events';
 import type { FapiClient, FapiRequestCallback } from './fapiClient';
 import { createFapiClient } from './fapiClient';
 import { createClientFromJwt } from './jwt-client';
+import { APIKeys } from './modules/apiKeys';
 import { CommerceBilling } from './modules/commerce';
 import {
  BaseResource,
@@ -163,6 +167,7 @@ const CANNOT_RENDER_USER_MISSING_ERROR_CODE = 'cannot_render_user_missing';
 const CANNOT_RENDER_ORGANIZATIONS_DISABLED_ERROR_CODE = 'cannot_render_organizations_disabled';
 const CANNOT_RENDER_ORGANIZATION_MISSING_ERROR_CODE = 'cannot_render_organization_missing';
 const CANNOT_RENDER_SINGLE_SESSION_ENABLED_ERROR_CODE = 'cannot_render_single_session_enabled';
+const CANNOT_RENDER_API_KEYS_DISABLED_ERROR_CODE = 'cannot_render_api_keys_disabled';
 const defaultOptions: ClerkOptions = {
  polling: true,
  standardBrowser: true,
@@ -189,6 +194,7 @@ export class Clerk implements ClerkInterface {
  environment: process.env.NODE_ENV || 'production',
  };
  private static _billing: CommerceBillingNamespace;
+ private static _apiKeys: APIKeysNamespace;
 
  public client: ClientResource | undefined;
  public session: SignedInSessionResource | null | undefined;
@@ -324,6 +330,13 @@ export class Clerk implements ClerkInterface {
  return Clerk._billing;
  }
 
+ get apiKeys(): APIKeysNamespace {
+ if (!Clerk._apiKeys) {
+ Clerk._apiKeys = new APIKeys();
+ }
+ return Clerk._apiKeys;
+ }
+
  public __internal_getOption<K extends keyof ClerkOptions>(key: K): ClerkOptions[K] {
  return this.#options[key];
  }
@@ -1055,6 +1068,53 @@ export class Clerk implements ClerkInterface {
  void this.#componentControls.ensureMounted().then(controls => controls.unmountComponent({ node }));
  };
 
+ /**
+ * @experimental
+ * This API is in early access and may change in future releases.
+ *
+ * Mount a api keys component at the target element.
+ * @param targetNode Target to mount the APIKeys component.
+ * @param props Configuration parameters.
+ */
+ public mountApiKeys = (node: HTMLDivElement, props?: APIKeysProps) => {
+ this.assertComponentsReady(this.#componentControls);
+
+ logger.warnOnce('Clerk: <APIKeys /> component is in early access and not yet recommended for production use.');
+
+ if (disabledAPIKeysFeature(this, this.environment)) {
+ if (this.#instanceType === 'development') {
+ throw new ClerkRuntimeError(warnings.cannotRenderAPIKeysComponent, {
+ code: CANNOT_RENDER_API_KEYS_DISABLED_ERROR_CODE,
+ });
+ }
+ return;
+ }
+ void this.#componentControls.ensureMounted({ preloadHint: 'APIKeys' }).then(controls =>
+ controls.mountComponent({
+ name: 'APIKeys',
+ appearanceKey: 'apiKeys',
+ node,
+ props,
+ }),
+ );
+
+ this.telemetry?.record(eventPrebuiltComponentMounted('APIKeys', props));
+ };
+
+ /**
+ * @experimental
+ * This API is in early access and may change in future releases.
+ *
+ * Unmount a api keys component from the target element.
+ * If there is no component mounted at the target node, results in a noop.
+ *
+ * @param targetNode Target node to unmount the ApiKeys component from.
+ */
+ public unmountApiKeys = (node: HTMLDivElement) => {
+ this.assertComponentsReady(this.#componentControls);
+ void this.#componentControls.ensureMounted().then(controls => controls.unmountComponent({ node }));
+ };
+
  /**
  * `setActive` can be used to set the active session and/or organization.
  */

packages/clerk-js/src/core/fapiClient.ts

@@ -225,8 +225,8 @@ export function createFapiClient(options: FapiClientOptions): FapiClient {
  const urlStr = requestInit.url.toString();
  const fetchOpts: FapiRequestInit = {
  ...requestInit,
- credentials: 'include',
  method: overwrittenRequestMethod,
+ credentials: requestInit.credentials || 'include',
  };
 
  try {

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

@@ -0,0 +1,101 @@
+import type {
+ ApiKeyJSON,
+ APIKeyResource,
+ APIKeysNamespace,
+ CreateAPIKeyParams,
+ GetAPIKeysParams,
+ RevokeAPIKeyParams,
+} from '@clerk/types';
+
+import type { FapiRequestInit } from '@/core/fapiClient';
+
+import { APIKey, BaseResource, ClerkRuntimeError } from '../../resources/internal';
+
+export class APIKeys implements APIKeysNamespace {
+ /**
+ * Returns the base options for the FAPI proxy requests.
+ */
+ private async getBaseFapiProxyOptions(): Promise<FapiRequestInit> {
+ const token = await BaseResource.clerk.session?.getToken();
+ if (!token) {
+ throw new ClerkRuntimeError('No valid session token available', { code: 'no_session_token' });
+ }
+
+ return {
+ // Set to an empty string because FAPI Proxy does not include the version in the path.
+ pathPrefix: '',
+ // Set the session token as a Bearer token in the Authorization header for authentication.
+ headers: {
+ Authorization: `Bearer ${token}`,
+ 'Content-Type': 'application/json',
+ },
+ // Set to `same-origin` to ensure cookies and credentials are sent with requests, avoiding CORS issues.
+ credentials: 'same-origin',
+ };
+ }
+
+ 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 ?? '',
+ },
+ })
+ .then(res => {
+ const apiKeysJSON = res.payload as unknown as { api_keys: ApiKeyJSON[] };
+ return apiKeysJSON.api_keys.map(json => new APIKey(json));
+ });
+ }
+
+ async getSecret(id: string): Promise<string> {
+ return BaseResource.clerk
+ .getFapiClient()
+ .request<{ secret: string }>({
+ ...(await this.getBaseFapiProxyOptions()),
+ method: 'GET',
+ path: `/api_keys/${id}/secret`,
+ })
+ .then(res => {
+ const { secret } = res.payload as unknown as { secret: string };
+ return secret;
+ });
+ }
+
+ async create(params: CreateAPIKeyParams): Promise<APIKeyResource> {
+ const json = (
+ await BaseResource._fetch<ApiKeyJSON>({
+ ...(await this.getBaseFapiProxyOptions()),
+ path: '/api_keys',
+ method: 'POST',
+ body: JSON.stringify({
+ type: params.type ?? 'api_key',
+ name: params.name,
+ subject: params.subject ?? BaseResource.clerk.organization?.id ?? BaseResource.clerk.user?.id ?? '',
+ description: params.description,
+ seconds_until_expiration: params.secondsUntilExpiration,
+ }),
+ })
+ )?.response as ApiKeyJSON;
+
+ return new APIKey(json);
+ }
+
+ async revoke(params: RevokeAPIKeyParams): Promise<APIKeyResource> {
+ const json = (
+ await BaseResource._fetch<ApiKeyJSON>({
+ ...(await this.getBaseFapiProxyOptions()),
+ method: 'POST',
+ path: `/api_keys/${params.apiKeyID}/revoke`,
+ body: JSON.stringify({
+ revocation_reason: params.revocationReason,
+ }),
+ })
+ )?.response as ApiKeyJSON;
+
+ return new APIKey(json);
+ }
+}

packages/clerk-js/src/core/resources/APIKey.ts

@@ -0,0 +1,73 @@
+import type { ApiKeyJSON, APIKeyResource } from '@clerk/types';
+
+import { unixEpochToDate } from '../../utils/date';
+import { BaseResource } from './internal';
+
+export class APIKey extends BaseResource implements APIKeyResource {
+ pathRoot = '/api_keys';
+
+ id!: string;
+ type!: string;
+ name!: string;
+ subject!: string;
+ scopes!: string[];
+ claims!: Record<string, any> | null;
+ revoked!: boolean;
+ revocationReason!: string | null;
+ expired!: boolean;
+ expiration!: Date | null;
+ createdBy!: string | null;
+ description!: string | null;
+ lastUsedAt!: Date | null;
+ createdAt!: Date;
+ updatedAt!: Date;
+
+ constructor(data: ApiKeyJSON) {
+ super();
+ this.fromJSON(data);
+ }
+
+ protected fromJSON(data: ApiKeyJSON | null): this {
+ if (!data) {
+ return this;
+ }
+
+ this.id = data.id;
+ this.type = data.type;
+ this.name = data.name;
+ this.subject = data.subject;
+ this.scopes = data.scopes;
+ this.claims = data.claims;
+ this.revoked = data.revoked;
+ this.revocationReason = data.revocation_reason;
+ this.expired = data.expired;
+ this.expiration = data.expiration ? unixEpochToDate(data.expiration) : null;
+ this.createdBy = data.created_by;
+ this.description = data.description;
+ this.lastUsedAt = data.last_used_at ? unixEpochToDate(data.last_used_at) : null;
+ this.updatedAt = unixEpochToDate(data.updated_at);
+ this.createdAt = unixEpochToDate(data.created_at);
+ return this;
+ }
+
+ public __internal_toSnapshot(): ApiKeyJSON {
+ return {
+ object: 'api_key',
+ id: this.id,
+ type: this.type,
+ name: this.name,
+ subject: this.subject,
+ scopes: this.scopes,
+ claims: this.claims,
+ revoked: this.revoked,
+ revocation_reason: this.revocationReason,
+ expired: this.expired,
+ expiration: this.expiration ? this.expiration.getTime() : null,
+ created_by: this.createdBy,
+ description: this.description,
+ last_used_at: this.lastUsedAt ? this.lastUsedAt.getTime() : null,
+ created_at: this.createdAt.getTime(),
+ updated_at: this.updatedAt.getTime(),
+ };
+ }
+}

.changeset/fluffy-numbers-stick.md

@@ -0,0 +1,6 @@
+---
+'@clerk/localizations': patch
+'@clerk/types': patch
+---
+
+Add TypeScript types and en-US localization for upcoming `<APIKeys />` component. This component will initially be in early access.

.changeset/ninety-candles-sleep.md

@@ -0,0 +1,7 @@
+---
+'@clerk/clerk-js': minor
+'@clerk/nextjs': minor
+'@clerk/clerk-react': minor
+---
+
+Add `<APIKeys />` component. This component will initially be in early access and not recommended for production usage just yet.

.typedoc/__tests__/__snapshots__/file-structure.test.ts.snap

@@ -129,6 +129,7 @@ exports[`Typedoc output > should have a deliberate file structure 1`] = `
  "nextjs/create-sync-get-auth.mdx",
  "nextjs/current-user.mdx",
  "nextjs/get-auth.mdx",
+ "clerk-react/api-keys.mdx",
  "clerk-react/clerk-provider-props.mdx",
  "clerk-react/protect.mdx",
  "clerk-react/redirect-to-create-organization.mdx",

packages/chrome-extension/src/__tests__/__snapshots__/exports.test.ts.snap

@@ -2,6 +2,7 @@
 
 exports[`public exports should not include a breaking change 1`] = `
 [
+ "APIKeys",
  "AuthenticateWithRedirectCallback",
  "ClerkDegraded",
  "ClerkFailed",

packages/clerk-js/bundlewatch.config.json

@@ -1,10 +1,10 @@
 {
  "files": [
- { "path": "./dist/clerk.js", "maxSize": "605kB" },
- { "path": "./dist/clerk.browser.js", "maxSize": "69.3KB" },
+ { "path": "./dist/clerk.js", "maxSize": "608.89kB" },
+ { "path": "./dist/clerk.browser.js", "maxSize": "70.15KB" },
  { "path": "./dist/clerk.legacy.browser.js", "maxSize": "113KB" },
- { "path": "./dist/clerk.headless*.js", "maxSize": "53KB" },
- { "path": "./dist/ui-common*.js", "maxSize": "107.5KB" },
+ { "path": "./dist/clerk.headless*.js", "maxSize": "53.06KB" },
+ { "path": "./dist/ui-common*.js", "maxSize": "108.35KB" },
  { "path": "./dist/vendors*.js", "maxSize": "40.2KB" },
  { "path": "./dist/coinbase*.js", "maxSize": "38KB" },
  { "path": "./dist/createorganization*.js", "maxSize": "5KB" },

packages/clerk-js/sandbox/app.ts

@@ -33,6 +33,7 @@ const AVAILABLE_COMPONENTS = [
  'organizationSwitcher',
  'waitlist',
  'pricingTable',
+ 'apiKeys',
  'oauthConsent',
 ] as const;
 
@@ -92,6 +93,7 @@ const componentControls: Record<(typeof AVAILABLE_COMPONENTS)[number], Component
  organizationSwitcher: buildComponentControls('organizationSwitcher'),
  waitlist: buildComponentControls('waitlist'),
  pricingTable: buildComponentControls('pricingTable'),
+ apiKeys: buildComponentControls('apiKeys'),
  oauthConsent: buildComponentControls('oauthConsent'),
 };
 
@@ -312,6 +314,9 @@ void (async () => {
  '/pricing-table': () => {
  Clerk.mountPricingTable(app, componentControls.pricingTable.getProps() ?? {});
  },
+ '/api-keys': () => {
+ Clerk.mountApiKeys(app, componentControls.apiKeys.getProps() ?? {});
+ },
  '/oauth-consent': () => {
  const searchParams = new URLSearchParams(window.location.search);
  const scopes = (searchParams.get('scopes')?.split(',') ?? []).map(scope => ({

packages/clerk-js/sandbox/template.html

@@ -260,6 +260,14 @@
  PricingTable
  </a>
  </li>
+ <li class="relative">
+ <a
+ class="relative isolate flex w-full rounded-md border border-white px-2 py-[0.4375rem] text-sm hover:bg-gray-50 aria-[current]:bg-gray-50"
+ href="/api-keys"
+ >
+ API Keys
+ </a>
+ </li>
  <li class="relative">
  <a
  class="relative isolate flex w-full rounded-md border border-white px-2 py-[0.4375rem] text-sm hover:bg-gray-50 aria-[current]:bg-gray-50"

packages/clerk-js/src/core/clerk.ts

@@ -20,6 +20,8 @@ import type {
  __internal_OAuthConsentProps,
  __internal_PlanDetailsProps,
  __internal_UserVerificationModalProps,
+ APIKeysNamespace,
+ APIKeysProps,
  AuthenticateWithCoinbaseWalletParams,
  AuthenticateWithGoogleOneTapParams,
  AuthenticateWithMetamaskParams,
@@ -88,6 +90,7 @@ import {
  createAllowedRedirectOrigins,
  createBeforeUnloadTracker,
  createPageLifecycle,
+ disabledAPIKeysFeature,
  disabledBillingFeature,
  disabledOrganizationsFeature,
  errorThrower,
@@ -132,6 +135,7 @@ import { eventBus, events } from './events';
 import type { FapiClient, FapiRequestCallback } from './fapiClient';
 import { createFapiClient } from './fapiClient';
 import { createClientFromJwt } from './jwt-client';
+import { APIKeys } from './modules/apiKeys';
 import { CommerceBilling } from './modules/commerce';
 import {
  BaseResource,
@@ -163,6 +167,7 @@ const CANNOT_RENDER_USER_MISSING_ERROR_CODE = 'cannot_render_user_missing';
 const CANNOT_RENDER_ORGANIZATIONS_DISABLED_ERROR_CODE = 'cannot_render_organizations_disabled';
 const CANNOT_RENDER_ORGANIZATION_MISSING_ERROR_CODE = 'cannot_render_organization_missing';
 const CANNOT_RENDER_SINGLE_SESSION_ENABLED_ERROR_CODE = 'cannot_render_single_session_enabled';
+const CANNOT_RENDER_API_KEYS_DISABLED_ERROR_CODE = 'cannot_render_api_keys_disabled';
 const defaultOptions: ClerkOptions = {
  polling: true,
  standardBrowser: true,
@@ -189,6 +194,7 @@ export class Clerk implements ClerkInterface {
  environment: process.env.NODE_ENV || 'production',
  };
  private static _billing: CommerceBillingNamespace;
+ private static _apiKeys: APIKeysNamespace;
 
  public client: ClientResource | undefined;
  public session: SignedInSessionResource | null | undefined;
@@ -324,6 +330,13 @@ export class Clerk implements ClerkInterface {
  return Clerk._billing;
  }
 
+ get apiKeys(): APIKeysNamespace {
+ if (!Clerk._apiKeys) {
+ Clerk._apiKeys = new APIKeys();
+ }
+ return Clerk._apiKeys;
+ }
+
  public __internal_getOption<K extends keyof ClerkOptions>(key: K): ClerkOptions[K] {
  return this.#options[key];
  }
@@ -1055,6 +1068,53 @@ export class Clerk implements ClerkInterface {
  void this.#componentControls.ensureMounted().then(controls => controls.unmountComponent({ node }));
  };
 
+ /**
+ * @experimental
+ * This API is in early access and may change in future releases.
+ *
+ * Mount a api keys component at the target element.
+ * @param targetNode Target to mount the APIKeys component.
+ * @param props Configuration parameters.
+ */
+ public mountApiKeys = (node: HTMLDivElement, props?: APIKeysProps) => {
+ this.assertComponentsReady(this.#componentControls);
+
+ logger.warnOnce('Clerk: <APIKeys /> component is in early access and not yet recommended for production use.');
+
+ if (disabledAPIKeysFeature(this, this.environment)) {
+ if (this.#instanceType === 'development') {
+ throw new ClerkRuntimeError(warnings.cannotRenderAPIKeysComponent, {
+ code: CANNOT_RENDER_API_KEYS_DISABLED_ERROR_CODE,
+ });
+ }
+ return;
+ }
+ void this.#componentControls.ensureMounted({ preloadHint: 'APIKeys' }).then(controls =>
+ controls.mountComponent({
+ name: 'APIKeys',
+ appearanceKey: 'apiKeys',
+ node,
+ props,
+ }),
+ );
+
+ this.telemetry?.record(eventPrebuiltComponentMounted('APIKeys', props));
+ };
+
+ /**
+ * @experimental
+ * This API is in early access and may change in future releases.
+ *
+ * Unmount a api keys component from the target element.
+ * If there is no component mounted at the target node, results in a noop.
+ *
+ * @param targetNode Target node to unmount the ApiKeys component from.
+ */
+ public unmountApiKeys = (node: HTMLDivElement) => {
+ this.assertComponentsReady(this.#componentControls);
+ void this.#componentControls.ensureMounted().then(controls => controls.unmountComponent({ node }));
+ };
+
  /**
  * `setActive` can be used to set the active session and/or organization.
  */

packages/clerk-js/src/core/fapiClient.ts

@@ -225,8 +225,8 @@ export function createFapiClient(options: FapiClientOptions): FapiClient {
  const urlStr = requestInit.url.toString();
  const fetchOpts: FapiRequestInit = {
  ...requestInit,
- credentials: 'include',
  method: overwrittenRequestMethod,
+ credentials: requestInit.credentials || 'include',
  };
 
  try {

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

@@ -0,0 +1,101 @@
+import type {
+ ApiKeyJSON,
+ APIKeyResource,
+ APIKeysNamespace,
+ CreateAPIKeyParams,
+ GetAPIKeysParams,
+ RevokeAPIKeyParams,
+} from '@clerk/types';
+
+import type { FapiRequestInit } from '@/core/fapiClient';
+
+import { APIKey, BaseResource, ClerkRuntimeError } from '../../resources/internal';
+
+export class APIKeys implements APIKeysNamespace {
+ /**
+ * Returns the base options for the FAPI proxy requests.
+ */
+ private async getBaseFapiProxyOptions(): Promise<FapiRequestInit> {
+ const token = await BaseResource.clerk.session?.getToken();
+ if (!token) {
+ throw new ClerkRuntimeError('No valid session token available', { code: 'no_session_token' });
+ }
+
+ return {
+ // Set to an empty string because FAPI Proxy does not include the version in the path.
+ pathPrefix: '',
+ // Set the session token as a Bearer token in the Authorization header for authentication.
+ headers: {
+ Authorization: `Bearer ${token}`,
+ 'Content-Type': 'application/json',
+ },
+ // Set to `same-origin` to ensure cookies and credentials are sent with requests, avoiding CORS issues.
+ credentials: 'same-origin',
+ };
+ }
+
+ 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 ?? '',
+ },
+ })
+ .then(res => {
+ const apiKeysJSON = res.payload as unknown as { api_keys: ApiKeyJSON[] };
+ return apiKeysJSON.api_keys.map(json => new APIKey(json));
+ });
+ }
+
+ async getSecret(id: string): Promise<string> {
+ return BaseResource.clerk
+ .getFapiClient()
+ .request<{ secret: string }>({
+ ...(await this.getBaseFapiProxyOptions()),
+ method: 'GET',
+ path: `/api_keys/${id}/secret`,
+ })
+ .then(res => {
+ const { secret } = res.payload as unknown as { secret: string };
+ return secret;
+ });
+ }
+
+ async create(params: CreateAPIKeyParams): Promise<APIKeyResource> {
+ const json = (
+ await BaseResource._fetch<ApiKeyJSON>({
+ ...(await this.getBaseFapiProxyOptions()),
+ path: '/api_keys',
+ method: 'POST',
+ body: JSON.stringify({
+ type: params.type ?? 'api_key',
+ name: params.name,
+ subject: params.subject ?? BaseResource.clerk.organization?.id ?? BaseResource.clerk.user?.id ?? '',
+ description: params.description,
+ seconds_until_expiration: params.secondsUntilExpiration,
+ }),
+ })
+ )?.response as ApiKeyJSON;
+
+ return new APIKey(json);
+ }
+
+ async revoke(params: RevokeAPIKeyParams): Promise<APIKeyResource> {
+ const json = (
+ await BaseResource._fetch<ApiKeyJSON>({
+ ...(await this.getBaseFapiProxyOptions()),
+ method: 'POST',
+ path: `/api_keys/${params.apiKeyID}/revoke`,
+ body: JSON.stringify({
+ revocation_reason: params.revocationReason,
+ }),
+ })
+ )?.response as ApiKeyJSON;
+
+ return new APIKey(json);
+ }
+}

packages/clerk-js/src/core/resources/APIKey.ts

@@ -0,0 +1,73 @@
+import type { ApiKeyJSON, APIKeyResource } from '@clerk/types';
+
+import { unixEpochToDate } from '../../utils/date';
+import { BaseResource } from './internal';
+
+export class APIKey extends BaseResource implements APIKeyResource {
+ pathRoot = '/api_keys';
+
+ id!: string;
+ type!: string;
+ name!: string;
+ subject!: string;
+ scopes!: string[];
+ claims!: Record<string, any> | null;
+ revoked!: boolean;
+ revocationReason!: string | null;
+ expired!: boolean;
+ expiration!: Date | null;
+ createdBy!: string | null;
+ description!: string | null;
+ lastUsedAt!: Date | null;
+ createdAt!: Date;
+ updatedAt!: Date;
+
+ constructor(data: ApiKeyJSON) {
+ super();
+ this.fromJSON(data);
+ }
+
+ protected fromJSON(data: ApiKeyJSON | null): this {
+ if (!data) {
+ return this;
+ }
+
+ this.id = data.id;
+ this.type = data.type;
+ this.name = data.name;
+ this.subject = data.subject;
+ this.scopes = data.scopes;
+ this.claims = data.claims;
+ this.revoked = data.revoked;
+ this.revocationReason = data.revocation_reason;
+ this.expired = data.expired;
+ this.expiration = data.expiration ? unixEpochToDate(data.expiration) : null;
+ this.createdBy = data.created_by;
+ this.description = data.description;
+ this.lastUsedAt = data.last_used_at ? unixEpochToDate(data.last_used_at) : null;
+ this.updatedAt = unixEpochToDate(data.updated_at);
+ this.createdAt = unixEpochToDate(data.created_at);
+ return this;
+ }
+
+ public __internal_toSnapshot(): ApiKeyJSON {
+ return {
+ object: 'api_key',
+ id: this.id,
+ type: this.type,
+ name: this.name,
+ subject: this.subject,
+ scopes: this.scopes,
+ claims: this.claims,
+ revoked: this.revoked,
+ revocation_reason: this.revocationReason,
+ expired: this.expired,
+ expiration: this.expiration ? this.expiration.getTime() : null,
+ created_by: this.createdBy,
+ description: this.description,
+ last_used_at: this.lastUsedAt ? this.lastUsedAt.getTime() : null,
+ created_at: this.createdAt.getTime(),
+ updated_at: this.updatedAt.getTime(),
+ };
+ }
+}

.changeset/fluffy-numbers-stick.md

@@ -0,0 +1,6 @@
+---
+'@clerk/localizations': patch
+'@clerk/types': patch
+---
+
+Add TypeScript types and en-US localization for upcoming `<APIKeys />` component. This component will initially be in early access.

.changeset/ninety-candles-sleep.md

@@ -0,0 +1,7 @@
+---
+'@clerk/clerk-js': minor
+'@clerk/nextjs': minor
+'@clerk/clerk-react': minor
+---
+
+Add `<APIKeys />` component. This component will initially be in early access and not recommended for production usage just yet.

.typedoc/__tests__/__snapshots__/file-structure.test.ts.snap

@@ -129,6 +129,7 @@ exports[`Typedoc output > should have a deliberate file structure 1`] = `
  "nextjs/create-sync-get-auth.mdx",
  "nextjs/current-user.mdx",
  "nextjs/get-auth.mdx",
+ "clerk-react/api-keys.mdx",
  "clerk-react/clerk-provider-props.mdx",
  "clerk-react/protect.mdx",
  "clerk-react/redirect-to-create-organization.mdx",

packages/chrome-extension/src/__tests__/__snapshots__/exports.test.ts.snap

@@ -2,6 +2,7 @@
 
 exports[`public exports should not include a breaking change 1`] = `
 [
+ "APIKeys",
  "AuthenticateWithRedirectCallback",
  "ClerkDegraded",
  "ClerkFailed",

packages/clerk-js/bundlewatch.config.json

@@ -1,10 +1,10 @@
 {
  "files": [
- { "path": "./dist/clerk.js", "maxSize": "605kB" },
- { "path": "./dist/clerk.browser.js", "maxSize": "69.3KB" },
+ { "path": "./dist/clerk.js", "maxSize": "608.89kB" },
+ { "path": "./dist/clerk.browser.js", "maxSize": "70.15KB" },
  { "path": "./dist/clerk.legacy.browser.js", "maxSize": "113KB" },
- { "path": "./dist/clerk.headless*.js", "maxSize": "53KB" },
- { "path": "./dist/ui-common*.js", "maxSize": "107.5KB" },
+ { "path": "./dist/clerk.headless*.js", "maxSize": "53.06KB" },
+ { "path": "./dist/ui-common*.js", "maxSize": "108.35KB" },
  { "path": "./dist/vendors*.js", "maxSize": "40.2KB" },
  { "path": "./dist/coinbase*.js", "maxSize": "38KB" },
  { "path": "./dist/createorganization*.js", "maxSize": "5KB" },

packages/clerk-js/sandbox/app.ts

@@ -33,6 +33,7 @@ const AVAILABLE_COMPONENTS = [
  'organizationSwitcher',
  'waitlist',
  'pricingTable',
+ 'apiKeys',
  'oauthConsent',
 ] as const;
 
@@ -92,6 +93,7 @@ const componentControls: Record<(typeof AVAILABLE_COMPONENTS)[number], Component
  organizationSwitcher: buildComponentControls('organizationSwitcher'),
  waitlist: buildComponentControls('waitlist'),
  pricingTable: buildComponentControls('pricingTable'),
+ apiKeys: buildComponentControls('apiKeys'),
  oauthConsent: buildComponentControls('oauthConsent'),
 };
 
@@ -312,6 +314,9 @@ void (async () => {
  '/pricing-table': () => {
  Clerk.mountPricingTable(app, componentControls.pricingTable.getProps() ?? {});
  },
+ '/api-keys': () => {
+ Clerk.mountApiKeys(app, componentControls.apiKeys.getProps() ?? {});
+ },
  '/oauth-consent': () => {
  const searchParams = new URLSearchParams(window.location.search);
  const scopes = (searchParams.get('scopes')?.split(',') ?? []).map(scope => ({

packages/clerk-js/sandbox/template.html

@@ -260,6 +260,14 @@
  PricingTable
  </a>
  </li>
+ <li class="relative">
+ <a
+ class="relative isolate flex w-full rounded-md border border-white px-2 py-[0.4375rem] text-sm hover:bg-gray-50 aria-[current]:bg-gray-50"
+ href="/api-keys"
+ >
+ API Keys
+ </a>
+ </li>
  <li class="relative">
  <a
  class="relative isolate flex w-full rounded-md border border-white px-2 py-[0.4375rem] text-sm hover:bg-gray-50 aria-[current]:bg-gray-50"

packages/clerk-js/src/core/clerk.ts

@@ -20,6 +20,8 @@ import type {
  __internal_OAuthConsentProps,
  __internal_PlanDetailsProps,
  __internal_UserVerificationModalProps,
+ APIKeysNamespace,
+ APIKeysProps,
  AuthenticateWithCoinbaseWalletParams,
  AuthenticateWithGoogleOneTapParams,
  AuthenticateWithMetamaskParams,
@@ -88,6 +90,7 @@ import {
  createAllowedRedirectOrigins,
  createBeforeUnloadTracker,
  createPageLifecycle,
+ disabledAPIKeysFeature,
  disabledBillingFeature,
  disabledOrganizationsFeature,
  errorThrower,
@@ -132,6 +135,7 @@ import { eventBus, events } from './events';
 import type { FapiClient, FapiRequestCallback } from './fapiClient';
 import { createFapiClient } from './fapiClient';
 import { createClientFromJwt } from './jwt-client';
+import { APIKeys } from './modules/apiKeys';
 import { CommerceBilling } from './modules/commerce';
 import {
  BaseResource,
@@ -163,6 +167,7 @@ const CANNOT_RENDER_USER_MISSING_ERROR_CODE = 'cannot_render_user_missing';
 const CANNOT_RENDER_ORGANIZATIONS_DISABLED_ERROR_CODE = 'cannot_render_organizations_disabled';
 const CANNOT_RENDER_ORGANIZATION_MISSING_ERROR_CODE = 'cannot_render_organization_missing';
 const CANNOT_RENDER_SINGLE_SESSION_ENABLED_ERROR_CODE = 'cannot_render_single_session_enabled';
+const CANNOT_RENDER_API_KEYS_DISABLED_ERROR_CODE = 'cannot_render_api_keys_disabled';
 const defaultOptions: ClerkOptions = {
  polling: true,
  standardBrowser: true,
@@ -189,6 +194,7 @@ export class Clerk implements ClerkInterface {
  environment: process.env.NODE_ENV || 'production',
  };
  private static _billing: CommerceBillingNamespace;
+ private static _apiKeys: APIKeysNamespace;
 
  public client: ClientResource | undefined;
  public session: SignedInSessionResource | null | undefined;
@@ -324,6 +330,13 @@ export class Clerk implements ClerkInterface {
  return Clerk._billing;
  }
 
+ get apiKeys(): APIKeysNamespace {
+ if (!Clerk._apiKeys) {
+ Clerk._apiKeys = new APIKeys();
+ }
+ return Clerk._apiKeys;
+ }
+
  public __internal_getOption<K extends keyof ClerkOptions>(key: K): ClerkOptions[K] {
  return this.#options[key];
  }
@@ -1055,6 +1068,53 @@ export class Clerk implements ClerkInterface {
  void this.#componentControls.ensureMounted().then(controls => controls.unmountComponent({ node }));
  };
 
+ /**
+ * @experimental
+ * This API is in early access and may change in future releases.
+ *
+ * Mount a api keys component at the target element.
+ * @param targetNode Target to mount the APIKeys component.
+ * @param props Configuration parameters.
+ */
+ public mountApiKeys = (node: HTMLDivElement, props?: APIKeysProps) => {
+ this.assertComponentsReady(this.#componentControls);
+
+ logger.warnOnce('Clerk: <APIKeys /> component is in early access and not yet recommended for production use.');
+
+ if (disabledAPIKeysFeature(this, this.environment)) {
+ if (this.#instanceType === 'development') {
+ throw new ClerkRuntimeError(warnings.cannotRenderAPIKeysComponent, {
+ code: CANNOT_RENDER_API_KEYS_DISABLED_ERROR_CODE,
+ });
+ }
+ return;
+ }
+ void this.#componentControls.ensureMounted({ preloadHint: 'APIKeys' }).then(controls =>
+ controls.mountComponent({
+ name: 'APIKeys',
+ appearanceKey: 'apiKeys',
+ node,
+ props,
+ }),
+ );
+
+ this.telemetry?.record(eventPrebuiltComponentMounted('APIKeys', props));
+ };
+
+ /**
+ * @experimental
+ * This API is in early access and may change in future releases.
+ *
+ * Unmount a api keys component from the target element.
+ * If there is no component mounted at the target node, results in a noop.
+ *
+ * @param targetNode Target node to unmount the ApiKeys component from.
+ */
+ public unmountApiKeys = (node: HTMLDivElement) => {
+ this.assertComponentsReady(this.#componentControls);
+ void this.#componentControls.ensureMounted().then(controls => controls.unmountComponent({ node }));
+ };
+
  /**
  * `setActive` can be used to set the active session and/or organization.
  */

packages/clerk-js/src/core/fapiClient.ts

@@ -225,8 +225,8 @@ export function createFapiClient(options: FapiClientOptions): FapiClient {
  const urlStr = requestInit.url.toString();
  const fetchOpts: FapiRequestInit = {
  ...requestInit,
- credentials: 'include',
  method: overwrittenRequestMethod,
+ credentials: requestInit.credentials || 'include',
  };
 
  try {

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

@@ -0,0 +1,101 @@
+import type {
+ ApiKeyJSON,
+ APIKeyResource,
+ APIKeysNamespace,
+ CreateAPIKeyParams,
+ GetAPIKeysParams,
+ RevokeAPIKeyParams,
+} from '@clerk/types';
+
+import type { FapiRequestInit } from '@/core/fapiClient';
+
+import { APIKey, BaseResource, ClerkRuntimeError } from '../../resources/internal';
+
+export class APIKeys implements APIKeysNamespace {
+ /**
+ * Returns the base options for the FAPI proxy requests.
+ */
+ private async getBaseFapiProxyOptions(): Promise<FapiRequestInit> {
+ const token = await BaseResource.clerk.session?.getToken();
+ if (!token) {
+ throw new ClerkRuntimeError('No valid session token available', { code: 'no_session_token' });
+ }
+
+ return {
+ // Set to an empty string because FAPI Proxy does not include the version in the path.
+ pathPrefix: '',
+ // Set the session token as a Bearer token in the Authorization header for authentication.
+ headers: {
+ Authorization: `Bearer ${token}`,
+ 'Content-Type': 'application/json',
+ },
+ // Set to `same-origin` to ensure cookies and credentials are sent with requests, avoiding CORS issues.
+ credentials: 'same-origin',
+ };
+ }
+
+ 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 ?? '',
+ },
+ })
+ .then(res => {
+ const apiKeysJSON = res.payload as unknown as { api_keys: ApiKeyJSON[] };
+ return apiKeysJSON.api_keys.map(json => new APIKey(json));
+ });
+ }
+
+ async getSecret(id: string): Promise<string> {
+ return BaseResource.clerk
+ .getFapiClient()
+ .request<{ secret: string }>({
+ ...(await this.getBaseFapiProxyOptions()),
+ method: 'GET',
+ path: `/api_keys/${id}/secret`,
+ })
+ .then(res => {
+ const { secret } = res.payload as unknown as { secret: string };
+ return secret;
+ });
+ }
+
+ async create(params: CreateAPIKeyParams): Promise<APIKeyResource> {
+ const json = (
+ await BaseResource._fetch<ApiKeyJSON>({
+ ...(await this.getBaseFapiProxyOptions()),
+ path: '/api_keys',
+ method: 'POST',
+ body: JSON.stringify({
+ type: params.type ?? 'api_key',
+ name: params.name,
+ subject: params.subject ?? BaseResource.clerk.organization?.id ?? BaseResource.clerk.user?.id ?? '',
+ description: params.description,
+ seconds_until_expiration: params.secondsUntilExpiration,
+ }),
+ })
+ )?.response as ApiKeyJSON;
+
+ return new APIKey(json);
+ }
+
+ async revoke(params: RevokeAPIKeyParams): Promise<APIKeyResource> {
+ const json = (
+ await BaseResource._fetch<ApiKeyJSON>({
+ ...(await this.getBaseFapiProxyOptions()),
+ method: 'POST',
+ path: `/api_keys/${params.apiKeyID}/revoke`,
+ body: JSON.stringify({
+ revocation_reason: params.revocationReason,
+ }),
+ })
+ )?.response as ApiKeyJSON;
+
+ return new APIKey(json);
+ }
+}

packages/clerk-js/src/core/resources/APIKey.ts

@@ -0,0 +1,73 @@
+import type { ApiKeyJSON, APIKeyResource } from '@clerk/types';
+
+import { unixEpochToDate } from '../../utils/date';
+import { BaseResource } from './internal';
+
+export class APIKey extends BaseResource implements APIKeyResource {
+ pathRoot = '/api_keys';
+
+ id!: string;
+ type!: string;
+ name!: string;
+ subject!: string;
+ scopes!: string[];
+ claims!: Record<string, any> | null;
+ revoked!: boolean;
+ revocationReason!: string | null;
+ expired!: boolean;
+ expiration!: Date | null;
+ createdBy!: string | null;
+ description!: string | null;
+ lastUsedAt!: Date | null;
+ createdAt!: Date;
+ updatedAt!: Date;
+
+ constructor(data: ApiKeyJSON) {
+ super();
+ this.fromJSON(data);
+ }
+
+ protected fromJSON(data: ApiKeyJSON | null): this {
+ if (!data) {
+ return this;
+ }
+
+ this.id = data.id;
+ this.type = data.type;
+ this.name = data.name;
+ this.subject = data.subject;
+ this.scopes = data.scopes;
+ this.claims = data.claims;
+ this.revoked = data.revoked;
+ this.revocationReason = data.revocation_reason;
+ this.expired = data.expired;
+ this.expiration = data.expiration ? unixEpochToDate(data.expiration) : null;
+ this.createdBy = data.created_by;
+ this.description = data.description;
+ this.lastUsedAt = data.last_used_at ? unixEpochToDate(data.last_used_at) : null;
+ this.updatedAt = unixEpochToDate(data.updated_at);
+ this.createdAt = unixEpochToDate(data.created_at);
+ return this;
+ }
+
+ public __internal_toSnapshot(): ApiKeyJSON {
+ return {
+ object: 'api_key',
+ id: this.id,
+ type: this.type,
+ name: this.name,
+ subject: this.subject,
+ scopes: this.scopes,
+ claims: this.claims,
+ revoked: this.revoked,
+ revocation_reason: this.revocationReason,
+ expired: this.expired,
+ expiration: this.expiration ? this.expiration.getTime() : null,
+ created_by: this.createdBy,
+ description: this.description,
+ last_used_at: this.lastUsedAt ? this.lastUsedAt.getTime() : null,
+ created_at: this.createdAt.getTime(),
+ updated_at: this.updatedAt.getTime(),
+ };
+ }
+}

.changeset/fluffy-numbers-stick.md

@@ -0,0 +1,6 @@
+---
+'@clerk/localizations': patch
+'@clerk/types': patch
+---
+
+Add TypeScript types and en-US localization for upcoming `<APIKeys />` component. This component will initially be in early access.

.changeset/ninety-candles-sleep.md

@@ -0,0 +1,7 @@
+---
+'@clerk/clerk-js': minor
+'@clerk/nextjs': minor
+'@clerk/clerk-react': minor
+---
+
+Add `<APIKeys />` component. This component will initially be in early access and not recommended for production usage just yet.

.typedoc/__tests__/__snapshots__/file-structure.test.ts.snap

@@ -129,6 +129,7 @@ exports[`Typedoc output > should have a deliberate file structure 1`] = `
  "nextjs/create-sync-get-auth.mdx",
  "nextjs/current-user.mdx",
  "nextjs/get-auth.mdx",
+ "clerk-react/api-keys.mdx",
  "clerk-react/clerk-provider-props.mdx",
  "clerk-react/protect.mdx",
  "clerk-react/redirect-to-create-organization.mdx",

packages/chrome-extension/src/__tests__/__snapshots__/exports.test.ts.snap

@@ -2,6 +2,7 @@
 
 exports[`public exports should not include a breaking change 1`] = `
 [
+ "APIKeys",
  "AuthenticateWithRedirectCallback",
  "ClerkDegraded",
  "ClerkFailed",

packages/clerk-js/bundlewatch.config.json

@@ -1,10 +1,10 @@
 {
  "files": [
- { "path": "./dist/clerk.js", "maxSize": "605kB" },
- { "path": "./dist/clerk.browser.js", "maxSize": "69.3KB" },
+ { "path": "./dist/clerk.js", "maxSize": "608.89kB" },
+ { "path": "./dist/clerk.browser.js", "maxSize": "70.15KB" },
  { "path": "./dist/clerk.legacy.browser.js", "maxSize": "113KB" },
- { "path": "./dist/clerk.headless*.js", "maxSize": "53KB" },
- { "path": "./dist/ui-common*.js", "maxSize": "107.5KB" },
+ { "path": "./dist/clerk.headless*.js", "maxSize": "53.06KB" },
+ { "path": "./dist/ui-common*.js", "maxSize": "108.35KB" },
  { "path": "./dist/vendors*.js", "maxSize": "40.2KB" },
  { "path": "./dist/coinbase*.js", "maxSize": "38KB" },
  { "path": "./dist/createorganization*.js", "maxSize": "5KB" },

packages/clerk-js/sandbox/app.ts

@@ -33,6 +33,7 @@ const AVAILABLE_COMPONENTS = [
  'organizationSwitcher',
  'waitlist',
  'pricingTable',
+ 'apiKeys',
  'oauthConsent',
 ] as const;
 
@@ -92,6 +93,7 @@ const componentControls: Record<(typeof AVAILABLE_COMPONENTS)[number], Component
  organizationSwitcher: buildComponentControls('organizationSwitcher'),
  waitlist: buildComponentControls('waitlist'),
  pricingTable: buildComponentControls('pricingTable'),
+ apiKeys: buildComponentControls('apiKeys'),
  oauthConsent: buildComponentControls('oauthConsent'),
 };
 
@@ -312,6 +314,9 @@ void (async () => {
  '/pricing-table': () => {
  Clerk.mountPricingTable(app, componentControls.pricingTable.getProps() ?? {});
  },
+ '/api-keys': () => {
+ Clerk.mountApiKeys(app, componentControls.apiKeys.getProps() ?? {});
+ },
  '/oauth-consent': () => {
  const searchParams = new URLSearchParams(window.location.search);
  const scopes = (searchParams.get('scopes')?.split(',') ?? []).map(scope => ({

packages/clerk-js/sandbox/template.html

@@ -260,6 +260,14 @@
  PricingTable
  </a>
  </li>
+ <li class="relative">
+ <a
+ class="relative isolate flex w-full rounded-md border border-white px-2 py-[0.4375rem] text-sm hover:bg-gray-50 aria-[current]:bg-gray-50"
+ href="/api-keys"
+ >
+ API Keys
+ </a>
+ </li>
  <li class="relative">
  <a
  class="relative isolate flex w-full rounded-md border border-white px-2 py-[0.4375rem] text-sm hover:bg-gray-50 aria-[current]:bg-gray-50"

packages/clerk-js/src/core/clerk.ts

@@ -20,6 +20,8 @@ import type {
  __internal_OAuthConsentProps,
  __internal_PlanDetailsProps,
  __internal_UserVerificationModalProps,
+ APIKeysNamespace,
+ APIKeysProps,
  AuthenticateWithCoinbaseWalletParams,
  AuthenticateWithGoogleOneTapParams,
  AuthenticateWithMetamaskParams,
@@ -88,6 +90,7 @@ import {
  createAllowedRedirectOrigins,
  createBeforeUnloadTracker,
  createPageLifecycle,
+ disabledAPIKeysFeature,
  disabledBillingFeature,
  disabledOrganizationsFeature,
  errorThrower,
@@ -132,6 +135,7 @@ import { eventBus, events } from './events';
 import type { FapiClient, FapiRequestCallback } from './fapiClient';
 import { createFapiClient } from './fapiClient';
 import { createClientFromJwt } from './jwt-client';
+import { APIKeys } from './modules/apiKeys';
 import { CommerceBilling } from './modules/commerce';
 import {
  BaseResource,
@@ -163,6 +167,7 @@ const CANNOT_RENDER_USER_MISSING_ERROR_CODE = 'cannot_render_user_missing';
 const CANNOT_RENDER_ORGANIZATIONS_DISABLED_ERROR_CODE = 'cannot_render_organizations_disabled';
 const CANNOT_RENDER_ORGANIZATION_MISSING_ERROR_CODE = 'cannot_render_organization_missing';
 const CANNOT_RENDER_SINGLE_SESSION_ENABLED_ERROR_CODE = 'cannot_render_single_session_enabled';
+const CANNOT_RENDER_API_KEYS_DISABLED_ERROR_CODE = 'cannot_render_api_keys_disabled';
 const defaultOptions: ClerkOptions = {
  polling: true,
  standardBrowser: true,
@@ -189,6 +194,7 @@ export class Clerk implements ClerkInterface {
  environment: process.env.NODE_ENV || 'production',
  };
  private static _billing: CommerceBillingNamespace;
+ private static _apiKeys: APIKeysNamespace;
 
  public client: ClientResource | undefined;
  public session: SignedInSessionResource | null | undefined;
@@ -324,6 +330,13 @@ export class Clerk implements ClerkInterface {
  return Clerk._billing;
  }
 
+ get apiKeys(): APIKeysNamespace {
+ if (!Clerk._apiKeys) {
+ Clerk._apiKeys = new APIKeys();
+ }
+ return Clerk._apiKeys;
+ }
+
  public __internal_getOption<K extends keyof ClerkOptions>(key: K): ClerkOptions[K] {
  return this.#options[key];
  }
@@ -1055,6 +1068,53 @@ export class Clerk implements ClerkInterface {
  void this.#componentControls.ensureMounted().then(controls => controls.unmountComponent({ node }));
  };
 
+ /**
+ * @experimental
+ * This API is in early access and may change in future releases.
+ *
+ * Mount a api keys component at the target element.
+ * @param targetNode Target to mount the APIKeys component.
+ * @param props Configuration parameters.
+ */
+ public mountApiKeys = (node: HTMLDivElement, props?: APIKeysProps) => {
+ this.assertComponentsReady(this.#componentControls);
+
+ logger.warnOnce('Clerk: <APIKeys /> component is in early access and not yet recommended for production use.');
+
+ if (disabledAPIKeysFeature(this, this.environment)) {
+ if (this.#instanceType === 'development') {
+ throw new ClerkRuntimeError(warnings.cannotRenderAPIKeysComponent, {
+ code: CANNOT_RENDER_API_KEYS_DISABLED_ERROR_CODE,
+ });
+ }
+ return;
+ }
+ void this.#componentControls.ensureMounted({ preloadHint: 'APIKeys' }).then(controls =>
+ controls.mountComponent({
+ name: 'APIKeys',
+ appearanceKey: 'apiKeys',
+ node,
+ props,
+ }),
+ );
+
+ this.telemetry?.record(eventPrebuiltComponentMounted('APIKeys', props));
+ };
+
+ /**
+ * @experimental
+ * This API is in early access and may change in future releases.
+ *
+ * Unmount a api keys component from the target element.
+ * If there is no component mounted at the target node, results in a noop.
+ *
+ * @param targetNode Target node to unmount the ApiKeys component from.
+ */
+ public unmountApiKeys = (node: HTMLDivElement) => {
+ this.assertComponentsReady(this.#componentControls);
+ void this.#componentControls.ensureMounted().then(controls => controls.unmountComponent({ node }));
+ };
+
  /**
  * `setActive` can be used to set the active session and/or organization.
  */

packages/clerk-js/src/core/fapiClient.ts

@@ -225,8 +225,8 @@ export function createFapiClient(options: FapiClientOptions): FapiClient {
  const urlStr = requestInit.url.toString();
  const fetchOpts: FapiRequestInit = {
  ...requestInit,
- credentials: 'include',
  method: overwrittenRequestMethod,
+ credentials: requestInit.credentials || 'include',
  };
 
  try {

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

@@ -0,0 +1,101 @@
+import type {
+ ApiKeyJSON,
+ APIKeyResource,
+ APIKeysNamespace,
+ CreateAPIKeyParams,
+ GetAPIKeysParams,
+ RevokeAPIKeyParams,
+} from '@clerk/types';
+
+import type { FapiRequestInit } from '@/core/fapiClient';
+
+import { APIKey, BaseResource, ClerkRuntimeError } from '../../resources/internal';
+
+export class APIKeys implements APIKeysNamespace {
+ /**
+ * Returns the base options for the FAPI proxy requests.
+ */
+ private async getBaseFapiProxyOptions(): Promise<FapiRequestInit> {
+ const token = await BaseResource.clerk.session?.getToken();
+ if (!token) {
+ throw new ClerkRuntimeError('No valid session token available', { code: 'no_session_token' });
+ }
+
+ return {
+ // Set to an empty string because FAPI Proxy does not include the version in the path.
+ pathPrefix: '',
+ // Set the session token as a Bearer token in the Authorization header for authentication.
+ headers: {
+ Authorization: `Bearer ${token}`,
+ 'Content-Type': 'application/json',
+ },
+ // Set to `same-origin` to ensure cookies and credentials are sent with requests, avoiding CORS issues.
+ credentials: 'same-origin',
+ };
+ }
+
+ 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 ?? '',
+ },
+ })
+ .then(res => {
+ const apiKeysJSON = res.payload as unknown as { api_keys: ApiKeyJSON[] };
+ return apiKeysJSON.api_keys.map(json => new APIKey(json));
+ });
+ }
+
+ async getSecret(id: string): Promise<string> {
+ return BaseResource.clerk
+ .getFapiClient()
+ .request<{ secret: string }>({
+ ...(await this.getBaseFapiProxyOptions()),
+ method: 'GET',
+ path: `/api_keys/${id}/secret`,
+ })
+ .then(res => {
+ const { secret } = res.payload as unknown as { secret: string };
+ return secret;
+ });
+ }
+
+ async create(params: CreateAPIKeyParams): Promise<APIKeyResource> {
+ const json = (
+ await BaseResource._fetch<ApiKeyJSON>({
+ ...(await this.getBaseFapiProxyOptions()),
+ path: '/api_keys',
+ method: 'POST',
+ body: JSON.stringify({
+ type: params.type ?? 'api_key',
+ name: params.name,
+ subject: params.subject ?? BaseResource.clerk.organization?.id ?? BaseResource.clerk.user?.id ?? '',
+ description: params.description,
+ seconds_until_expiration: params.secondsUntilExpiration,
+ }),
+ })
+ )?.response as ApiKeyJSON;
+
+ return new APIKey(json);
+ }
+
+ async revoke(params: RevokeAPIKeyParams): Promise<APIKeyResource> {
+ const json = (
+ await BaseResource._fetch<ApiKeyJSON>({
+ ...(await this.getBaseFapiProxyOptions()),
+ method: 'POST',
+ path: `/api_keys/${params.apiKeyID}/revoke`,
+ body: JSON.stringify({
+ revocation_reason: params.revocationReason,
+ }),
+ })
+ )?.response as ApiKeyJSON;
+
+ return new APIKey(json);
+ }
+}

packages/clerk-js/src/core/resources/APIKey.ts

@@ -0,0 +1,73 @@
+import type { ApiKeyJSON, APIKeyResource } from '@clerk/types';
+
+import { unixEpochToDate } from '../../utils/date';
+import { BaseResource } from './internal';
+
+export class APIKey extends BaseResource implements APIKeyResource {
+ pathRoot = '/api_keys';
+
+ id!: string;
+ type!: string;
+ name!: string;
+ subject!: string;
+ scopes!: string[];
+ claims!: Record<string, any> | null;
+ revoked!: boolean;
+ revocationReason!: string | null;
+ expired!: boolean;
+ expiration!: Date | null;
+ createdBy!: string | null;
+ description!: string | null;
+ lastUsedAt!: Date | null;
+ createdAt!: Date;
+ updatedAt!: Date;
+
+ constructor(data: ApiKeyJSON) {
+ super();
+ this.fromJSON(data);
+ }
+
+ protected fromJSON(data: ApiKeyJSON | null): this {
+ if (!data) {
+ return this;
+ }
+
+ this.id = data.id;
+ this.type = data.type;
+ this.name = data.name;
+ this.subject = data.subject;
+ this.scopes = data.scopes;
+ this.claims = data.claims;
+ this.revoked = data.revoked;
+ this.revocationReason = data.revocation_reason;
+ this.expired = data.expired;
+ this.expiration = data.expiration ? unixEpochToDate(data.expiration) : null;
+ this.createdBy = data.created_by;
+ this.description = data.description;
+ this.lastUsedAt = data.last_used_at ? unixEpochToDate(data.last_used_at) : null;
+ this.updatedAt = unixEpochToDate(data.updated_at);
+ this.createdAt = unixEpochToDate(data.created_at);
+ return this;
+ }
+
+ public __internal_toSnapshot(): ApiKeyJSON {
+ return {
+ object: 'api_key',
+ id: this.id,
+ type: this.type,
+ name: this.name,
+ subject: this.subject,
+ scopes: this.scopes,
+ claims: this.claims,
+ revoked: this.revoked,
+ revocation_reason: this.revocationReason,
+ expired: this.expired,
+ expiration: this.expiration ? this.expiration.getTime() : null,
+ created_by: this.createdBy,
+ description: this.description,
+ last_used_at: this.lastUsedAt ? this.lastUsedAt.getTime() : null,
+ created_at: this.createdAt.getTime(),
+ updated_at: this.updatedAt.getTime(),
+ };
+ }
+}

.changeset/fluffy-numbers-stick.md

@@ -0,0 +1,6 @@
+---
+'@clerk/localizations': patch
+'@clerk/types': patch
+---
+
+Add TypeScript types and en-US localization for upcoming `<APIKeys />` component. This component will initially be in early access.

.changeset/ninety-candles-sleep.md

@@ -0,0 +1,7 @@
+---
+'@clerk/clerk-js': minor
+'@clerk/nextjs': minor
+'@clerk/clerk-react': minor
+---
+
+Add `<APIKeys />` component. This component will initially be in early access and not recommended for production usage just yet.

.typedoc/__tests__/__snapshots__/file-structure.test.ts.snap

@@ -129,6 +129,7 @@ exports[`Typedoc output > should have a deliberate file structure 1`] = `
  "nextjs/create-sync-get-auth.mdx",
  "nextjs/current-user.mdx",
  "nextjs/get-auth.mdx",
+ "clerk-react/api-keys.mdx",
  "clerk-react/clerk-provider-props.mdx",
  "clerk-react/protect.mdx",
  "clerk-react/redirect-to-create-organization.mdx",

packages/chrome-extension/src/__tests__/__snapshots__/exports.test.ts.snap

@@ -2,6 +2,7 @@
 
 exports[`public exports should not include a breaking change 1`] = `
 [
+ "APIKeys",
  "AuthenticateWithRedirectCallback",
  "ClerkDegraded",
  "ClerkFailed",

packages/clerk-js/bundlewatch.config.json

@@ -1,10 +1,10 @@
 {
  "files": [
- { "path": "./dist/clerk.js", "maxSize": "605kB" },
- { "path": "./dist/clerk.browser.js", "maxSize": "69.3KB" },
+ { "path": "./dist/clerk.js", "maxSize": "608.89kB" },
+ { "path": "./dist/clerk.browser.js", "maxSize": "70.15KB" },
  { "path": "./dist/clerk.legacy.browser.js", "maxSize": "113KB" },
- { "path": "./dist/clerk.headless*.js", "maxSize": "53KB" },
- { "path": "./dist/ui-common*.js", "maxSize": "107.5KB" },
+ { "path": "./dist/clerk.headless*.js", "maxSize": "53.06KB" },
+ { "path": "./dist/ui-common*.js", "maxSize": "108.35KB" },
  { "path": "./dist/vendors*.js", "maxSize": "40.2KB" },
  { "path": "./dist/coinbase*.js", "maxSize": "38KB" },
  { "path": "./dist/createorganization*.js", "maxSize": "5KB" },

packages/clerk-js/sandbox/app.ts

@@ -33,6 +33,7 @@ const AVAILABLE_COMPONENTS = [
  'organizationSwitcher',
  'waitlist',
  'pricingTable',
+ 'apiKeys',
  'oauthConsent',
 ] as const;
 
@@ -92,6 +93,7 @@ const componentControls: Record<(typeof AVAILABLE_COMPONENTS)[number], Component
  organizationSwitcher: buildComponentControls('organizationSwitcher'),
  waitlist: buildComponentControls('waitlist'),
  pricingTable: buildComponentControls('pricingTable'),
+ apiKeys: buildComponentControls('apiKeys'),
  oauthConsent: buildComponentControls('oauthConsent'),
 };
 
@@ -312,6 +314,9 @@ void (async () => {
  '/pricing-table': () => {
  Clerk.mountPricingTable(app, componentControls.pricingTable.getProps() ?? {});
  },
+ '/api-keys': () => {
+ Clerk.mountApiKeys(app, componentControls.apiKeys.getProps() ?? {});
+ },
  '/oauth-consent': () => {
  const searchParams = new URLSearchParams(window.location.search);
  const scopes = (searchParams.get('scopes')?.split(',') ?? []).map(scope => ({

packages/clerk-js/sandbox/template.html

@@ -260,6 +260,14 @@
  PricingTable
  </a>
  </li>
+ <li class="relative">
+ <a
+ class="relative isolate flex w-full rounded-md border border-white px-2 py-[0.4375rem] text-sm hover:bg-gray-50 aria-[current]:bg-gray-50"
+ href="/api-keys"
+ >
+ API Keys
+ </a>
+ </li>
  <li class="relative">
  <a
  class="relative isolate flex w-full rounded-md border border-white px-2 py-[0.4375rem] text-sm hover:bg-gray-50 aria-[current]:bg-gray-50"

packages/clerk-js/src/core/clerk.ts

@@ -20,6 +20,8 @@ import type {
  __internal_OAuthConsentProps,
  __internal_PlanDetailsProps,
  __internal_UserVerificationModalProps,
+ APIKeysNamespace,
+ APIKeysProps,
  AuthenticateWithCoinbaseWalletParams,
  AuthenticateWithGoogleOneTapParams,
  AuthenticateWithMetamaskParams,
@@ -88,6 +90,7 @@ import {
  createAllowedRedirectOrigins,
  createBeforeUnloadTracker,
  createPageLifecycle,
+ disabledAPIKeysFeature,
  disabledBillingFeature,
  disabledOrganizationsFeature,
  errorThrower,
@@ -132,6 +135,7 @@ import { eventBus, events } from './events';
 import type { FapiClient, FapiRequestCallback } from './fapiClient';
 import { createFapiClient } from './fapiClient';
 import { createClientFromJwt } from './jwt-client';
+import { APIKeys } from './modules/apiKeys';
 import { CommerceBilling } from './modules/commerce';
 import {
  BaseResource,
@@ -163,6 +167,7 @@ const CANNOT_RENDER_USER_MISSING_ERROR_CODE = 'cannot_render_user_missing';
 const CANNOT_RENDER_ORGANIZATIONS_DISABLED_ERROR_CODE = 'cannot_render_organizations_disabled';
 const CANNOT_RENDER_ORGANIZATION_MISSING_ERROR_CODE = 'cannot_render_organization_missing';
 const CANNOT_RENDER_SINGLE_SESSION_ENABLED_ERROR_CODE = 'cannot_render_single_session_enabled';
+const CANNOT_RENDER_API_KEYS_DISABLED_ERROR_CODE = 'cannot_render_api_keys_disabled';
 const defaultOptions: ClerkOptions = {
  polling: true,
  standardBrowser: true,
@@ -189,6 +194,7 @@ export class Clerk implements ClerkInterface {
  environment: process.env.NODE_ENV || 'production',
  };
  private static _billing: CommerceBillingNamespace;
+ private static _apiKeys: APIKeysNamespace;
 
  public client: ClientResource | undefined;
  public session: SignedInSessionResource | null | undefined;
@@ -324,6 +330,13 @@ export class Clerk implements ClerkInterface {
  return Clerk._billing;
  }
 
+ get apiKeys(): APIKeysNamespace {
+ if (!Clerk._apiKeys) {
+ Clerk._apiKeys = new APIKeys();
+ }
+ return Clerk._apiKeys;
+ }
+
  public __internal_getOption<K extends keyof ClerkOptions>(key: K): ClerkOptions[K] {
  return this.#options[key];
  }
@@ -1055,6 +1068,53 @@ export class Clerk implements ClerkInterface {
  void this.#componentControls.ensureMounted().then(controls => controls.unmountComponent({ node }));
  };
 
+ /**
+ * @experimental
+ * This API is in early access and may change in future releases.
+ *
+ * Mount a api keys component at the target element.
+ * @param targetNode Target to mount the APIKeys component.
+ * @param props Configuration parameters.
+ */
+ public mountApiKeys = (node: HTMLDivElement, props?: APIKeysProps) => {
+ this.assertComponentsReady(this.#componentControls);
+
+ logger.warnOnce('Clerk: <APIKeys /> component is in early access and not yet recommended for production use.');
+
+ if (disabledAPIKeysFeature(this, this.environment)) {
+ if (this.#instanceType === 'development') {
+ throw new ClerkRuntimeError(warnings.cannotRenderAPIKeysComponent, {
+ code: CANNOT_RENDER_API_KEYS_DISABLED_ERROR_CODE,
+ });
+ }
+ return;
+ }
+ void this.#componentControls.ensureMounted({ preloadHint: 'APIKeys' }).then(controls =>
+ controls.mountComponent({
+ name: 'APIKeys',
+ appearanceKey: 'apiKeys',
+ node,
+ props,
+ }),
+ );
+
+ this.telemetry?.record(eventPrebuiltComponentMounted('APIKeys', props));
+ };
+
+ /**
+ * @experimental
+ * This API is in early access and may change in future releases.
+ *
+ * Unmount a api keys component from the target element.
+ * If there is no component mounted at the target node, results in a noop.
+ *
+ * @param targetNode Target node to unmount the ApiKeys component from.
+ */
+ public unmountApiKeys = (node: HTMLDivElement) => {
+ this.assertComponentsReady(this.#componentControls);
+ void this.#componentControls.ensureMounted().then(controls => controls.unmountComponent({ node }));
+ };
+
  /**
  * `setActive` can be used to set the active session and/or organization.
  */

packages/clerk-js/src/core/fapiClient.ts

@@ -225,8 +225,8 @@ export function createFapiClient(options: FapiClientOptions): FapiClient {
  const urlStr = requestInit.url.toString();
  const fetchOpts: FapiRequestInit = {
  ...requestInit,
- credentials: 'include',
  method: overwrittenRequestMethod,
+ credentials: requestInit.credentials || 'include',
  };
 
  try {

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

@@ -0,0 +1,101 @@
+import type {
+ ApiKeyJSON,
+ APIKeyResource,
+ APIKeysNamespace,
+ CreateAPIKeyParams,
+ GetAPIKeysParams,
+ RevokeAPIKeyParams,
+} from '@clerk/types';
+
+import type { FapiRequestInit } from '@/core/fapiClient';
+
+import { APIKey, BaseResource, ClerkRuntimeError } from '../../resources/internal';
+
+export class APIKeys implements APIKeysNamespace {
+ /**
+ * Returns the base options for the FAPI proxy requests.
+ */
+ private async getBaseFapiProxyOptions(): Promise<FapiRequestInit> {
+ const token = await BaseResource.clerk.session?.getToken();
+ if (!token) {
+ throw new ClerkRuntimeError('No valid session token available', { code: 'no_session_token' });
+ }
+
+ return {
+ // Set to an empty string because FAPI Proxy does not include the version in the path.
+ pathPrefix: '',
+ // Set the session token as a Bearer token in the Authorization header for authentication.
+ headers: {
+ Authorization: `Bearer ${token}`,
+ 'Content-Type': 'application/json',
+ },
+ // Set to `same-origin` to ensure cookies and credentials are sent with requests, avoiding CORS issues.
+ credentials: 'same-origin',
+ };
+ }
+
+ 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 ?? '',
+ },
+ })
+ .then(res => {
+ const apiKeysJSON = res.payload as unknown as { api_keys: ApiKeyJSON[] };
+ return apiKeysJSON.api_keys.map(json => new APIKey(json));
+ });
+ }
+
+ async getSecret(id: string): Promise<string> {
+ return BaseResource.clerk
+ .getFapiClient()
+ .request<{ secret: string }>({
+ ...(await this.getBaseFapiProxyOptions()),
+ method: 'GET',
+ path: `/api_keys/${id}/secret`,
+ })
+ .then(res => {
+ const { secret } = res.payload as unknown as { secret: string };
+ return secret;
+ });
+ }
+
+ async create(params: CreateAPIKeyParams): Promise<APIKeyResource> {
+ const json = (
+ await BaseResource._fetch<ApiKeyJSON>({
+ ...(await this.getBaseFapiProxyOptions()),
+ path: '/api_keys',
+ method: 'POST',
+ body: JSON.stringify({
+ type: params.type ?? 'api_key',
+ name: params.name,
+ subject: params.subject ?? BaseResource.clerk.organization?.id ?? BaseResource.clerk.user?.id ?? '',
+ description: params.description,
+ seconds_until_expiration: params.secondsUntilExpiration,
+ }),
+ })
+ )?.response as ApiKeyJSON;
+
+ return new APIKey(json);
+ }
+
+ async revoke(params: RevokeAPIKeyParams): Promise<APIKeyResource> {
+ const json = (
+ await BaseResource._fetch<ApiKeyJSON>({
+ ...(await this.getBaseFapiProxyOptions()),
+ method: 'POST',
+ path: `/api_keys/${params.apiKeyID}/revoke`,
+ body: JSON.stringify({
+ revocation_reason: params.revocationReason,
+ }),
+ })
+ )?.response as ApiKeyJSON;
+
+ return new APIKey(json);
+ }
+}

packages/clerk-js/src/core/resources/APIKey.ts

@@ -0,0 +1,73 @@
+import type { ApiKeyJSON, APIKeyResource } from '@clerk/types';
+
+import { unixEpochToDate } from '../../utils/date';
+import { BaseResource } from './internal';
+
+export class APIKey extends BaseResource implements APIKeyResource {
+ pathRoot = '/api_keys';
+
+ id!: string;
+ type!: string;
+ name!: string;
+ subject!: string;
+ scopes!: string[];
+ claims!: Record<string, any> | null;
+ revoked!: boolean;
+ revocationReason!: string | null;
+ expired!: boolean;
+ expiration!: Date | null;
+ createdBy!: string | null;
+ description!: string | null;
+ lastUsedAt!: Date | null;
+ createdAt!: Date;
+ updatedAt!: Date;
+
+ constructor(data: ApiKeyJSON) {
+ super();
+ this.fromJSON(data);
+ }
+
+ protected fromJSON(data: ApiKeyJSON | null): this {
+ if (!data) {
+ return this;
+ }
+
+ this.id = data.id;
+ this.type = data.type;
+ this.name = data.name;
+ this.subject = data.subject;
+ this.scopes = data.scopes;
+ this.claims = data.claims;
+ this.revoked = data.revoked;
+ this.revocationReason = data.revocation_reason;
+ this.expired = data.expired;
+ this.expiration = data.expiration ? unixEpochToDate(data.expiration) : null;
+ this.createdBy = data.created_by;
+ this.description = data.description;
+ this.lastUsedAt = data.last_used_at ? unixEpochToDate(data.last_used_at) : null;
+ this.updatedAt = unixEpochToDate(data.updated_at);
+ this.createdAt = unixEpochToDate(data.created_at);
+ return this;
+ }
+
+ public __internal_toSnapshot(): ApiKeyJSON {
+ return {
+ object: 'api_key',
+ id: this.id,
+ type: this.type,
+ name: this.name,
+ subject: this.subject,
+ scopes: this.scopes,
+ claims: this.claims,
+ revoked: this.revoked,
+ revocation_reason: this.revocationReason,
+ expired: this.expired,
+ expiration: this.expiration ? this.expiration.getTime() : null,
+ created_by: this.createdBy,
+ description: this.description,
+ last_used_at: this.lastUsedAt ? this.lastUsedAt.getTime() : null,
+ created_at: this.createdAt.getTime(),
+ updated_at: this.updatedAt.getTime(),
+ };
+ }
+}