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.2KB" },
+    { "path": "./dist/clerk.js", "maxSize": "608.05kB" },
+    { "path": "./dist/clerk.browser.js", "maxSize": "70KB" },
     { "path": "./dist/clerk.legacy.browser.js", "maxSize": "113KB" },
     { "path": "./dist/clerk.headless*.js", "maxSize": "53KB" },
-    { "path": "./dist/ui-common*.js", "maxSize": "106.3KB" },
+    { "path": "./dist/ui-common*.js", "maxSize": "107.33KB" },
     { "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,48 @@ 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);
+    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,
+      }),
+    );
+  };
+
+  /**
+   * @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,103 @@
+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));
+      })
+      .catch(() => []);
+  }
+
+  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;
+      })
+      .catch(() => '');
+  }
+
+  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,52 @@
+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;
+  }
+}

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

@@ -0,0 +1,31 @@
+import type { APIKeysSettingsJSON, APIKeysSettingsJSONSnapshot, APIKeysSettingsResource } from '@clerk/types';
+
+import { BaseResource } from './internal';
+
+/**
+ * @internal
+ */
+export class APIKeySettings extends BaseResource implements APIKeysSettingsResource {
+  enabled: boolean = false;
+
+  public constructor(data: APIKeysSettingsJSON | APIKeysSettingsJSONSnapshot | null = null) {
+    super();
+    this.fromJSON(data);
+  }
+
+  protected fromJSON(data: APIKeysSettingsJSON | APIKeysSettingsJSONSnapshot | null): this {
+    if (!data) {
+      return this;
+    }
+
+    this.enabled = this.withDefault(data.enabled, false);
+
+    return this;
+  }
+
+  public __internal_toSnapshot(): APIKeysSettingsJSONSnapshot {
+    return {
+      enabled: this.enabled,
+    } as APIKeysSettingsJSONSnapshot;
+  }
+}