feat(api): add --fapi to call the public Frontend API

rafa-thayto · rafa-thayto · commit 020a2f5f8ec0 · 2026-06-18T09:13:32.000-03:00
clerk api spoke only BAPI and PLAPI, so verifying a config change against the instance's public FAPI /v1/environment (what clerk-js consumes) meant dropping to curl and decoding the FAPI domain out of the publishable key by hand. Add --fapi: resolve the FAPI host from the instance's publishable key (via --app/--instance or the linked project) and do an unauthenticated passthrough, reusing the existing lib/fapi.ts client. --fapi and --platform are mutually exclusive. Closes #332
diff --git a/.changeset/api-fapi-passthrough.md b/.changeset/api-fapi-passthrough.md
@@ -0,0 +1,5 @@
+---
+"clerk": minor
+---
+
+Add `clerk api --fapi` to call an instance's public Frontend API (e.g. `clerk api --fapi /environment --app <id>`). The FAPI host is resolved from the instance's publishable key, and the request is unauthenticated since these endpoints are public, which closes the loop on verifying config changes end to end with the CLI alone.
diff --git a/packages/cli-core/src/commands/api/README.md b/packages/cli-core/src/commands/api/README.md
@@ -55,22 +55,26 @@ clerk api /users --instance prod
 
 # Platform API mode
 clerk api /v1/platform/applications --platform
+
+# Frontend API mode — fetch the public environment payload to verify config
+clerk api --fapi /environment --app app_123 --instance dev
 ```
 
 ## Options
 
-| Flag                    | Description                                                       |
-| ----------------------- | ----------------------------------------------------------------- |
-| `-X, --method <method>` | HTTP method. Defaults to GET, or POST if body is provided.        |
-| `-d, --data <json>`     | JSON request body (inline)                                        |
-| `--file <path>`         | Read request body from a file                                     |
-| `--include`             | Show response status and headers                                  |
-| `--app <id>`            | Application ID to target when resolving keys                      |
-| `--secret-key <key>`    | Override the secret key                                           |
-| `--instance <id>`       | Instance to target for key resolution (`dev`, `prod`, or full ID) |
-| `--platform`            | Use Platform API instead of Backend API                           |
-| `--dry-run`             | Show request without executing                                    |
-| `--yes`                 | Skip confirmation for mutating requests                           |
+| Flag                    | Description                                                                     |
+| ----------------------- | ------------------------------------------------------------------------------- |
+| `-X, --method <method>` | HTTP method. Defaults to GET, or POST if body is provided.                      |
+| `-d, --data <json>`     | JSON request body (inline)                                                      |
+| `--file <path>`         | Read request body from a file                                                   |
+| `--include`             | Show response status and headers                                                |
+| `--app <id>`            | Application ID to target when resolving keys                                    |
+| `--secret-key <key>`    | Override the secret key                                                         |
+| `--instance <id>`       | Instance to target for key resolution (`dev`, `prod`, or full ID)               |
+| `--platform`            | Use Platform API instead of Backend API                                         |
+| `--fapi`                | Use the instance's public Frontend API (no auth; host from the publishable key) |
+| `--dry-run`             | Show request without executing                                                  |
+| `--yes`                 | Skip confirmation for mutating requests                                         |
 
 ## Authentication
 
@@ -94,6 +98,17 @@ Platform API auth (used by `--platform` mode, and by steps 3 and 4 above):
 
 The CLI validates key prefixes and will warn if you pass an `ak_` key where an `sk_` key is expected, or vice versa.
 
+### Frontend API (`--fapi`)
+
+`--fapi` targets the instance's public Frontend API — the same surface clerk-js
+consumes — which is useful for verifying that a config change took effect (e.g.
+`clerk api --fapi /environment`). The FAPI host is resolved from the instance's
+publishable key, looked up via the Platform API from `--app`/`--instance` or the
+linked project, so resolving the host needs Platform API auth, but the request
+itself is unauthenticated (these endpoints are public). `--fapi` and `--platform`
+cannot be combined. Paths are `/v1`-normalized like the other modes, so both
+`/environment` and `/v1/environment` work.
+
 ## API Endpoints
 
 ### Backend API (default)
diff --git a/packages/cli-core/src/commands/api/fapi.ts b/packages/cli-core/src/commands/api/fapi.ts
@@ -0,0 +1,109 @@
+/**
+ * Frontend API (FAPI) passthrough for `clerk api --fapi`.
+ *
+ * FAPI is the public API that clerk-js consumes. Its host is per-instance and
+ * derived from the instance's publishable key, and the endpoints exposed here
+ * (e.g. `/v1/environment`) are public, so no auth header is sent.
+ */
+
+import { resolveAppContext, resolveFetchedApplicationInstance } from "../../lib/config.ts";
+import { normalizeBapiPath } from "../../lib/bapi-command.ts";
+import {
+  CliError,
+  ERROR_CODE,
+  FapiError,
+  throwUsageError,
+  withApiContext,
+} from "../../lib/errors.ts";
+import { decodePublishableKey } from "../../lib/fapi.ts";
+import { loggedFetch } from "../../lib/fetch.ts";
+import { fetchApplication, type ApplicationInstance } from "../../lib/plapi.ts";
+import type { BapiResponse } from "./bapi.ts";
+
+/** clerk-js API version FAPI shapes its `/v1/environment` payload for. */
+const CLERK_JS_API_VERSION = "5";
+
+interface ResolveOptions {
+  app?: string;
+  instance?: string;
+}
+
+async function resolveInstance(options: ResolveOptions): Promise<ApplicationInstance> {
+  if (options.app) {
+    const app = await withApiContext(fetchApplication(options.app), "Failed to resolve instance");
+    const resolved = resolveFetchedApplicationInstance(options.app, app, options.instance);
+    if (!resolved.found) {
+      throw new CliError(`Instance ${resolved.instanceId} not found in application.`, {
+        code: ERROR_CODE.INSTANCE_NOT_FOUND,
+        docsUrl: "https://clerk.com/docs/guides/development/managing-environments",
+      });
+    }
+    return resolved.instance;
+  }
+
+  let ctx: Awaited<ReturnType<typeof resolveAppContext>>;
+  try {
+    ctx = await resolveAppContext({ app: options.app, instance: options.instance });
+  } catch (error) {
+    if (error instanceof CliError && error.code === ERROR_CODE.NOT_LINKED) {
+      throwUsageError(
+        "No instance found. Link a project with `clerk link`, or pass --app <app_id>.",
+        "https://clerk.com/docs/guides/development/managing-environments",
+        ERROR_CODE.NOT_LINKED,
+      );
+    }
+    throw error;
+  }
+
+  const app = await withApiContext(fetchApplication(ctx.appId), "Failed to resolve instance");
+  const instance = app.instances.find((entry) => entry.instance_id === ctx.instanceId);
+  if (!instance) {
+    throw new CliError(`Instance ${ctx.instanceId} not found in application.`, {
+      code: ERROR_CODE.INSTANCE_NOT_FOUND,
+      docsUrl: "https://clerk.com/docs/guides/development/managing-environments",
+    });
+  }
+  return instance;
+}
+
+/** Resolve the instance's FAPI host from its publishable key. */
+export async function resolveFapiHost(options: ResolveOptions): Promise<string> {
+  const instance = await resolveInstance(options);
+  return decodePublishableKey(instance.publishable_key).fapiHost;
+}
+
+export async function fapiRequest(options: {
+  method: string;
+  path: string;
+  fapiHost: string;
+  body?: string;
+}): Promise<BapiResponse> {
+  const url = new URL(`https://${options.fapiHost}${normalizeBapiPath(options.path)}`);
+  if (!url.searchParams.has("_clerk_js_version")) {
+    url.searchParams.set("_clerk_js_version", CLERK_JS_API_VERSION);
+  }
+
+  const headers: Record<string, string> = { Accept: "application/json" };
+  if (options.body) headers["Content-Type"] = "application/json";
+
+  const response = await loggedFetch(url, {
+    tag: "fapi",
+    method: options.method,
+    headers,
+    body: options.body,
+  });
+
+  if (!response.ok) {
+    throw await FapiError.fromResponse(response);
+  }
+
+  const rawBody = await response.text();
+  let body: unknown;
+  try {
+    body = JSON.parse(rawBody);
+  } catch {
+    body = rawBody;
+  }
+
+  return { status: response.status, headers: response.headers, body, rawBody };
+}
diff --git a/packages/cli-core/src/commands/api/index.test.ts b/packages/cli-core/src/commands/api/index.test.ts
@@ -476,6 +476,72 @@ describe("api command", () => {
     );
   });
 
+  // --- --fapi mode ---
+
+  test("--fapi resolves the FAPI host from the publishable key and sends no auth header", async () => {
+    delete process.env.CLERK_SECRET_KEY;
+    process.env.CLERK_PLATFORM_API_KEY = "ak_test_platform";
+    const pk = `pk_test_${btoa("clerk.example.com$")}`;
+    let fapiUrl = "";
+    let fapiAuth: string | null = "unset";
+
+    stubFetch(async (input, init) => {
+      const url = input.toString();
+      if (url.includes("/v1/platform/applications/app_1")) {
+        return new Response(
+          JSON.stringify({
+            application_id: "app_1",
+            instances: [
+              { instance_id: "ins_dev", environment_type: "development", publishable_key: pk },
+            ],
+          }),
+          { status: 200 },
+        );
+      }
+      fapiUrl = url;
+      fapiAuth = new Headers(init?.headers).get("Authorization");
+      return new Response(JSON.stringify({ environment: "ok" }), { status: 200 });
+    });
+
+    await runApi("/environment", { fapi: true, app: "app_1", instance: "dev" });
+    expect(fapiUrl).toContain("https://clerk.example.com/v1/environment");
+    expect(fapiUrl).toContain("_clerk_js_version=");
+    expect(fapiAuth).toBeNull();
+  });
+
+  test("--fapi cannot be combined with --platform", async () => {
+    await expect(runApi("/environment", { fapi: true, platform: true })).rejects.toThrow(
+      "cannot be combined",
+    );
+  });
+
+  test("--fapi prints API error response body to stdout and exits 1", async () => {
+    setMode("human");
+    process.env.CLERK_PLATFORM_API_KEY = "ak_test_platform";
+    const pk = `pk_test_${btoa("clerk.example.com$")}`;
+    const errorBody = { errors: [{ message: "no environment", code: "not_found" }] };
+
+    stubFetch(async (input) => {
+      const url = input.toString();
+      if (url.includes("/v1/platform/applications/app_1")) {
+        return new Response(
+          JSON.stringify({
+            application_id: "app_1",
+            instances: [
+              { instance_id: "ins_dev", environment_type: "development", publishable_key: pk },
+            ],
+          }),
+          { status: 200 },
+        );
+      }
+      return new Response(JSON.stringify(errorBody), { status: 404 });
+    });
+
+    await runApi("/environment", { fapi: true, app: "app_1" });
+    expect(process.exitCode).toBe(1);
+    expect(captured.out).toContain(JSON.stringify(errorBody, null, 2));
+  });
+
   // --- Error handling ---
 
   test("errors when no secret key available", async () => {
diff --git a/packages/cli-core/src/commands/api/index.ts b/packages/cli-core/src/commands/api/index.ts
@@ -2,9 +2,10 @@ import type { Program } from "../../cli-program.ts";
 import { getAuthToken } from "../../lib/plapi.ts";
 import { getBapiBaseUrl, getPlapiBaseUrl } from "../../lib/environment.ts";
 import { normalizeBapiPath, resolveBapiSecretKey } from "../../lib/bapi-command.ts";
-import { bapiRequest } from "./bapi.ts";
+import { bapiRequest, type BapiResponse } from "./bapi.ts";
+import { fapiRequest, resolveFapiHost } from "./fapi.ts";
 import {
-  BapiError,
+  ApiError,
   ERROR_CODE,
   UserAbortError,
   isPromptExitError,
@@ -25,12 +26,43 @@ export interface ApiOptions {
   secretKey?: string;
   instance?: string;
   platform?: boolean;
+  fapi?: boolean;
   dryRun?: boolean;
   yes?: boolean;
 }
 
 const MUTATING_METHODS = new Set(["POST", "PUT", "PATCH", "DELETE"]);
 
+type RunRequest = (req: { method: string; path: string; body?: string }) => Promise<BapiResponse>;
+
+/** Resolve the API surface (base URL + request executor) from the flags. */
+async function resolveApiTarget(
+  options: ApiOptions,
+): Promise<{ baseUrl: string; runRequest: RunRequest }> {
+  if (options.fapi) {
+    if (options.platform) {
+      throwUsageError(
+        "--fapi and --platform cannot be combined.",
+        undefined,
+        ERROR_CODE.USAGE_ERROR,
+      );
+    }
+    const fapiHost = await resolveFapiHost(options);
+    const baseUrl = `https://${fapiHost}`;
+    return { baseUrl, runRequest: (req) => fapiRequest({ ...req, fapiHost }) };
+  }
+
+  if (options.platform) {
+    const secretKey = await getAuthToken();
+    const baseUrl = getPlapiBaseUrl();
+    return { baseUrl, runRequest: (req) => bapiRequest({ ...req, secretKey, baseUrl }) };
+  }
+
+  const secretKey = await resolveBapiSecretKey(options);
+  const baseUrl = getBapiBaseUrl();
+  return { baseUrl, runRequest: (req) => bapiRequest({ ...req, secretKey, baseUrl }) };
+}
+
 export async function api(
   endpoint: string | undefined,
   filter: string | undefined,
@@ -61,17 +93,8 @@ export async function api(
     // 2. Determine HTTP method
     const method = (options.method ?? (body ? "POST" : "GET")).toUpperCase();
 
-    // 3. Resolve authentication
-    let secretKey: string;
-    let baseUrl: string;
-
-    if (options.platform) {
-      secretKey = await getAuthToken();
-      baseUrl = getPlapiBaseUrl();
-    } else {
-      secretKey = await resolveBapiSecretKey(options);
-      baseUrl = getBapiBaseUrl();
-    }
+    // 3. Resolve the request target (base URL + executor)
+    const { baseUrl, runRequest } = await resolveApiTarget(options);
 
     // 4. Dry run
     if (options.dryRun) {
@@ -97,13 +120,7 @@ export async function api(
     // 6. Execute request
     try {
       const response = await withSpinner("Executing request...", () =>
-        bapiRequest({
-          method,
-          path: endpoint,
-          secretKey,
-          body: body ?? undefined,
-          baseUrl,
-        }),
+        runRequest({ method, path: endpoint, body: body ?? undefined }),
       );
 
       if (options.include) {
@@ -112,10 +129,10 @@ export async function api(
       printBody(response.body);
       closeStatus = "success";
     } catch (error) {
-      // Handle BapiError locally to print the raw API response body to stdout
+      // Handle API errors locally to print the raw response body to stdout
       // (for piping), rather than propagating to the global error handler.
-      if (error instanceof BapiError) {
-        if (options.include) {
+      if (error instanceof ApiError) {
+        if (options.include && error.headers) {
           printHeaders(error.status, error.headers);
         }
         prettyPrint(error.body);
@@ -216,6 +233,10 @@ export function registerApi(program: Program): void {
     .option("--secret-key <key>", "Override the secret key")
     .option("--instance <id>", "Instance to target (dev, prod, or instance ID)")
     .option("--platform", "Use Platform API instead of Backend API")
+    .option(
+      "--fapi",
+      "Use the instance's public Frontend API (no auth; host resolved from the publishable key)",
+    )
     .option("--dry-run", "Show the request without executing it")
     .option("--yes", "Skip confirmation for mutating requests")
     .setExamples([
@@ -226,6 +247,10 @@ export function registerApi(program: Program): void {
         command: 'clerk api /users -d \'{"first_name":"Alice"}\'',
         description: "POST with a JSON body",
       },
+      {
+        command: "clerk api --fapi /environment --app <id> --instance dev",
+        description: "GET the public FAPI environment payload",
+      },
     ])
     .action(api);
 }

-Original file line number
+Diff line change
@@ @@ -0,0 +1,5 @@ @@
 +---
 +"clerk": minor
 +---
++
 +Add `clerk api --fapi` to call an instance's public Frontend API (e.g. `clerk api --fapi /environment --app <id>`). The FAPI host is resolved from the instance's publishable key, and the request is unauthenticated since these endpoints are public, which closes the loop on verifying config changes end to end with the CLI alone.