Support API Keys in clerk enable

.changeset/accept-orgs-users-for-flags.md

@@ -0,0 +1,5 @@
+---
+"clerk": minor
+---
+
+Add `clerk enable api-keys` and `clerk disable api-keys` for toggling API Keys on the linked instance. API Key targeting uses the canonical plural `orgs` and `users` values, while the singular `org` and `user` values continue to work as aliases.

packages/cli-core/src/cli-program.ts

@@ -48,6 +48,7 @@ import { update } from "./commands/update/index.ts";
 import { isClerkSkillInstalled } from "./lib/skill-detection.ts";
 import { orgsEnable, orgsDisable } from "./commands/orgs/index.ts";
 import { billingEnable, billingDisable } from "./commands/billing/index.ts";
+import { apiKeysEnable, apiKeysDisable } from "./commands/api-keys/index.ts";
 import { registerExtras } from "@clerk/cli-extras";
 
 const USER_LIST_ORDER_BY_FIELDS = [
@@ -636,6 +637,10 @@ Give AI agents better Clerk context: install the Clerk skills
  command: "clerk enable billing",
  description: "Enable billing for organizations and users",
  },
+ {
+ command: "clerk enable api-keys",
+ description: "Enable API Keys for users",
+ },
  ]);
 
  enable
@@ -703,6 +708,38 @@ Give AI agents better Clerk context: install the Clerk skills
  ])
  .action(billingEnable);
 
+ enable
+ .command("api-keys")
+ .aliases(["apikeys", "api_keys"])
+ .description("Enable API Keys on the linked instance")
+ .option(
+ "--for <targets...>",
+ "API Keys targets (orgs and/or users), separated by spaces or commas (e.g. orgs users). Defaults to users when omitted.",
+ )
+ .option("--app <id>", "Application ID to target")
+ .option("--instance <id>", "Instance to target (dev, prod, or instance ID)")
+ .option("--yes", "Skip confirmation prompts")
+ .option("--dry-run", "Show the patch that would be sent without applying it")
+ .setExamples([
+ {
+ command: "clerk enable api-keys",
+ description: "Enable API Keys for users",
+ },
+ {
+ command: "clerk enable api-keys --for orgs",
+ description: "Enable API Keys for organizations",
+ },
+ {
+ command: "clerk enable api-keys --for users orgs",
+ description: "Enable API Keys for users and organizations",
+ },
+ {
+ command: "clerk enable api-keys --dry-run",
+ description: "Preview the patch without applying it",
+ },
+ ])
+ .action(apiKeysEnable);
+
  const disable = program
  .command("disable")
  .description("Disable Clerk features on the linked instance")
@@ -716,6 +753,10 @@ Give AI agents better Clerk context: install the Clerk skills
  command: "clerk disable billing",
  description: "Disable billing for organizations and users",
  },
+ {
+ command: "clerk disable api-keys",
+ description: "Disable API Keys",
+ },
  ]);
 
  disable
@@ -764,6 +805,34 @@ Give AI agents better Clerk context: install the Clerk skills
  ])
  .action(billingDisable);
 
+ disable
+ .command("api-keys")
+ .aliases(["apikeys", "api_keys"])
+ .description("Disable API Keys on the linked instance")
+ .option(
+ "--for <targets...>",
+ "API Keys targets (orgs and/or users), separated by spaces or commas (e.g. orgs users). Omit to disable API Keys entirely.",
+ )
+ .option("--app <id>", "Application ID to target")
+ .option("--instance <id>", "Instance to target (dev, prod, or instance ID)")
+ .option("--yes", "Skip confirmation prompts")
+ .option("--dry-run", "Show the patch that would be sent without applying it")
+ .setExamples([
+ {
+ command: "clerk disable api-keys",
+ description: "Disable API Keys entirely",
+ },
+ {
+ command: "clerk disable api-keys --for orgs",
+ description: "Disable API Keys for organizations only",
+ },
+ {
+ command: "clerk disable api-keys --for users",
+ description: "Disable API Keys for users only",
+ },
+ ])
+ .action(apiKeysDisable);
+
  program
  .command("api")
  .description("Make authenticated requests to the Clerk API")

packages/cli-core/src/commands/api-keys/README.md

@@ -0,0 +1,52 @@
+# clerk api-keys (enable/disable)
+
+Toggle Clerk API Keys on the linked instance. The handlers are wired to
+top-level `clerk enable api-keys` and `clerk disable api-keys` commands.
+
+For arbitrary API Keys settings edits, use
+`clerk config patch --json '{"api_keys_settings":{...}}'`.
+
+## Usage
+
+```sh
+clerk enable api-keys [--for <targets>] [options]
+clerk disable api-keys [--for <targets>] [options]
+```
+
+`<targets>` is `orgs` and/or `users`, accepted as space-separated,
+comma-separated, or repeated `--for` flags. The singular aliases `org` and
+`user` are also accepted for backwards compatibility.
+
+```sh
+clerk enable api-keys # defaults to users
+clerk enable api-keys --for orgs users
+clerk enable api-keys --for orgs,users
+clerk disable api-keys # disables API Keys entirely
+clerk disable api-keys --for orgs # disables only organization API Keys
+```
+
+## Options
+
+| Flag | Description |
+| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
+| `--for <targets>` | Targets (`orgs` and/or `users`), separated by spaces or commas. Enable defaults to users; disable without `--for` disables API Keys entirely. |
+| `--app <id>` | Target a specific application |
+| `--instance <id>` | Target a specific instance (dev, prod) |
+| `--yes` | Skip the confirmation prompt |
+| `--dry-run` | Preview the patch without applying it |
+
+## Cascade behavior
+
+- `enable api-keys --for orgs` also sets `organization_settings.enabled = true`.
+ Organization API Keys require organizations enabled, so this saves a separate
+ command. The cascade is idempotent.
+- `disable api-keys --for orgs` disables only organization API Keys and leaves
+ organizations enabled.
+- `disable api-keys` without `--for` disables API Keys entirely.
+
+## Clerk API endpoints
+
+| Method | Endpoint | Description |
+| ------ | ----------------------------------------------------------------- | ----------------------------------------------------------------------- |
+| GET | `/v1/platform/applications/{appId}/instances/{instanceId}/config` | Fetch current config for diff before mutation |
+| PATCH | `/v1/platform/applications/{appId}/instances/{instanceId}/config` | Patch `api_keys_settings.*` (with `?dry_run=true` when `--dry-run` set) |

packages/cli-core/src/commands/api-keys/index.test.ts

@@ -0,0 +1,230 @@
+import { test, expect, describe, beforeEach, afterEach, spyOn, mock } from "bun:test";
+import { mkdtemp, rm } from "node:fs/promises";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { _setConfigDir, setProfile } from "../../lib/config.ts";
+import {
+ captureLog,
+ credentialStoreStubs,
+ gitStubs,
+ promptsStubs,
+ stubFetch,
+} from "../../test/lib/stubs.ts";
+
+mock.module("../../lib/credential-store.ts", () => credentialStoreStubs);
+mock.module("../../lib/git.ts", () => gitStubs);
+mock.module("@inquirer/prompts", () => promptsStubs);
+mock.module("../../lib/spinner.ts", () => ({
+ withSpinner: async (_msg: string, fn: () => Promise<unknown>) => fn(),
+}));
+
+describe("clerk enable/disable api-keys", () => {
+ const originalEnv = { ...process.env };
+ const originalFetch = globalThis.fetch;
+ let tempDir: string;
+ let logSpy: ReturnType<typeof spyOn>;
+ let errorSpy: ReturnType<typeof spyOn>;
+ let captured: ReturnType<typeof captureLog>;
+
+ beforeEach(async () => {
+ tempDir = await mkdtemp(join(tmpdir(), "clerk-api-keys-test-"));
+ _setConfigDir(tempDir);
+ process.env.CLERK_PLATFORM_API_KEY = "test_key";
+ process.env.CLERK_PLATFORM_API_URL = "https://test-api.clerk.com";
+
+ logSpy = spyOn(console, "log").mockImplementation(() => {});
+ errorSpy = spyOn(console, "error").mockImplementation(() => {});
+ captured = captureLog();
+
+ stubFetch(async () => {
+ return new Response(JSON.stringify({}), { status: 200 });
+ });
+ });
+
+ afterEach(async () => {
+ captured.teardown();
+ _setConfigDir(undefined);
+ process.env = { ...originalEnv };
+ globalThis.fetch = originalFetch;
+ logSpy.mockRestore();
+ errorSpy.mockRestore();
+ await rm(tempDir, { recursive: true, force: true });
+ });
+
+ async function setupProfile() {
+ await setProfile(process.cwd(), {
+ workspaceId: "org_1",
+ appId: "app_1",
+ instances: { development: "ins_dev" },
+ });
+ }
+
+ test("enable defaults to user API Keys", async () => {
+ let capturedBody = "";
+ stubFetch(async (_input, init) => {
+ if (init?.method === "PATCH") capturedBody = init.body as string;
+ return new Response(JSON.stringify({}), { status: 200 });
+ });
+
+ await setupProfile();
+ const { apiKeysEnable } = await import("./index.ts");
+ await captured.run(() => apiKeysEnable({}));
+
+ const parsed = JSON.parse(capturedBody);
+ expect(parsed.api_keys_settings.enabled).toBe(true);
+ expect(parsed.api_keys_settings.user_api_keys_enabled).toBe(true);
+ expect(parsed.api_keys_settings.orgs_api_keys_enabled).toBeUndefined();
+ expect(parsed.organization_settings).toBeUndefined();
+ });
+
+ test("enable --for orgs enables org API Keys and cascades organizations", async () => {
+ let capturedBody = "";
+ stubFetch(async (_input, init) => {
+ if (init?.method === "PATCH") capturedBody = init.body as string;
+ return new Response(JSON.stringify({}), { status: 200 });
+ });
+
+ await setupProfile();
+ const { apiKeysEnable } = await import("./index.ts");
+ await captured.run(() => apiKeysEnable({ for: ["orgs"] }));
+
+ const parsed = JSON.parse(capturedBody);
+ expect(parsed.api_keys_settings.enabled).toBe(true);
+ expect(parsed.api_keys_settings.orgs_api_keys_enabled).toBe(true);
+ expect(parsed.api_keys_settings.user_api_keys_enabled).toBeUndefined();
+ expect(parsed.organization_settings.enabled).toBe(true);
+ });
+
+ test("enable --for users,orgs sets both API Keys targets", async () => {
+ let capturedBody = "";
+ stubFetch(async (_input, init) => {
+ if (init?.method === "PATCH") capturedBody = init.body as string;
+ return new Response(JSON.stringify({}), { status: 200 });
+ });
+
+ await setupProfile();
+ const { apiKeysEnable } = await import("./index.ts");
+ await captured.run(() => apiKeysEnable({ for: ["users,orgs"] }));
+
+ const parsed = JSON.parse(capturedBody);
+ expect(parsed.api_keys_settings.user_api_keys_enabled).toBe(true);
+ expect(parsed.api_keys_settings.orgs_api_keys_enabled).toBe(true);
+ expect(parsed.organization_settings.enabled).toBe(true);
+ });
+
+ test("enable rejects invalid --for token", async () => {
+ await setupProfile();
+ const { apiKeysEnable } = await import("./index.ts");
+ await expect(captured.run(() => apiKeysEnable({ for: ["machine"] }))).rejects.toThrow(
+ 'Invalid --for value: "machine". Expected "orgs" and/or "users".',
+ );
+ });
+
+ test("enable accepts singular --for aliases", async () => {
+ let capturedBody = "";
+ stubFetch(async (_input, init) => {
+ if (init?.method === "PATCH") capturedBody = init.body as string;
+ return new Response(JSON.stringify({}), { status: 200 });
+ });
+
+ await setupProfile();
+ const { apiKeysEnable } = await import("./index.ts");
+ await captured.run(() => apiKeysEnable({ for: ["user", "org"] }));
+
+ const parsed = JSON.parse(capturedBody);
+ expect(parsed.api_keys_settings.user_api_keys_enabled).toBe(true);
+ expect(parsed.api_keys_settings.orgs_api_keys_enabled).toBe(true);
+ expect(parsed.organization_settings.enabled).toBe(true);
+ });
+
+ test("enable --dry-run plumbs dry_run=true to the API", async () => {
+ let capturedUrl = "";
+ stubFetch(async (input, init) => {
+ if (init?.method === "PATCH") capturedUrl = input.toString();
+ return new Response(JSON.stringify({}), { status: 200 });
+ });
+
+ await setupProfile();
+ const { apiKeysEnable } = await import("./index.ts");
+ await captured.run(() => apiKeysEnable({ dryRun: true }));
+
+ expect(capturedUrl).toContain("dry_run=true");
+ expect(captured.err).toContain("[dry-run]");
+ });
+
+ test("disable with no --for disables API Keys entirely", async () => {
+ let capturedBody = "";
+ stubFetch(async (_input, init) => {
+ if (init?.method === "PATCH") capturedBody = init.body as string;
+ return new Response(
+ JSON.stringify({
+ api_keys_settings: {
+ enabled: true,
+ user_api_keys_enabled: true,
+ orgs_api_keys_enabled: true,
+ },
+ }),
+ { status: 200 },
+ );
+ });
+
+ await setupProfile();
+ const { apiKeysDisable } = await import("./index.ts");
+ await captured.run(() => apiKeysDisable({}));
+
+ const parsed = JSON.parse(capturedBody);
+ expect(parsed.api_keys_settings.enabled).toBe(false);
+ expect(parsed.api_keys_settings.user_api_keys_enabled).toBe(false);
+ expect(parsed.api_keys_settings.orgs_api_keys_enabled).toBe(false);
+ });
+
+ test("disable --for orgs only disables org API Keys", async () => {
+ let capturedBody = "";
+ stubFetch(async (_input, init) => {
+ if (init?.method === "PATCH") capturedBody = init.body as string;
+ return new Response(
+ JSON.stringify({
+ api_keys_settings: {
+ enabled: true,
+ user_api_keys_enabled: true,
+ orgs_api_keys_enabled: true,
+ },
+ }),
+ { status: 200 },
+ );
+ });
+
+ await setupProfile();
+ const { apiKeysDisable } = await import("./index.ts");
+ await captured.run(() => apiKeysDisable({ for: ["orgs"] }));
+
+ const parsed = JSON.parse(capturedBody);
+ expect(parsed.api_keys_settings.enabled).toBeUndefined();
+ expect(parsed.api_keys_settings.user_api_keys_enabled).toBeUndefined();
+ expect(parsed.api_keys_settings.orgs_api_keys_enabled).toBe(false);
+ });
+
+ test("disable shows no changes when already fully disabled", async () => {
+ let patchCalls = 0;
+ stubFetch(async (_input, init) => {
+ if (init?.method === "PATCH") patchCalls++;
+ return new Response(
+ JSON.stringify({
+ api_keys_settings: {
+ enabled: false,
+ user_api_keys_enabled: false,
+ orgs_api_keys_enabled: false,
+ },
+ }),
+ { status: 200 },
+ );
+ });
+
+ await setupProfile();
+ const { apiKeysDisable } = await import("./index.ts");
+ await captured.run(() => apiKeysDisable({}));
+
+ expect(patchCalls).toBe(0);
+ expect(captured.err).toContain("No changes detected");
+ });
+});

.changeset/accept-orgs-users-for-flags.md

@@ -0,0 +1,5 @@
+---
+"clerk": minor
+---
+
+Add `clerk enable api-keys` and `clerk disable api-keys` for toggling API Keys on the linked instance. API Key targeting uses the canonical plural `orgs` and `users` values, while the singular `org` and `user` values continue to work as aliases.

packages/cli-core/src/cli-program.ts

@@ -48,6 +48,7 @@ import { update } from "./commands/update/index.ts";
 import { isClerkSkillInstalled } from "./lib/skill-detection.ts";
 import { orgsEnable, orgsDisable } from "./commands/orgs/index.ts";
 import { billingEnable, billingDisable } from "./commands/billing/index.ts";
+import { apiKeysEnable, apiKeysDisable } from "./commands/api-keys/index.ts";
 import { registerExtras } from "@clerk/cli-extras";
 
 const USER_LIST_ORDER_BY_FIELDS = [
@@ -636,6 +637,10 @@ Give AI agents better Clerk context: install the Clerk skills
  command: "clerk enable billing",
  description: "Enable billing for organizations and users",
  },
+ {
+ command: "clerk enable api-keys",
+ description: "Enable API Keys for users",
+ },
  ]);
 
  enable
@@ -703,6 +708,38 @@ Give AI agents better Clerk context: install the Clerk skills
  ])
  .action(billingEnable);
 
+ enable
+ .command("api-keys")
+ .aliases(["apikeys", "api_keys"])
+ .description("Enable API Keys on the linked instance")
+ .option(
+ "--for <targets...>",
+ "API Keys targets (orgs and/or users), separated by spaces or commas (e.g. orgs users). Defaults to users when omitted.",
+ )
+ .option("--app <id>", "Application ID to target")
+ .option("--instance <id>", "Instance to target (dev, prod, or instance ID)")
+ .option("--yes", "Skip confirmation prompts")
+ .option("--dry-run", "Show the patch that would be sent without applying it")
+ .setExamples([
+ {
+ command: "clerk enable api-keys",
+ description: "Enable API Keys for users",
+ },
+ {
+ command: "clerk enable api-keys --for orgs",
+ description: "Enable API Keys for organizations",
+ },
+ {
+ command: "clerk enable api-keys --for users orgs",
+ description: "Enable API Keys for users and organizations",
+ },
+ {
+ command: "clerk enable api-keys --dry-run",
+ description: "Preview the patch without applying it",
+ },
+ ])
+ .action(apiKeysEnable);
+
  const disable = program
  .command("disable")
  .description("Disable Clerk features on the linked instance")
@@ -716,6 +753,10 @@ Give AI agents better Clerk context: install the Clerk skills
  command: "clerk disable billing",
  description: "Disable billing for organizations and users",
  },
+ {
+ command: "clerk disable api-keys",
+ description: "Disable API Keys",
+ },
  ]);
 
  disable
@@ -764,6 +805,34 @@ Give AI agents better Clerk context: install the Clerk skills
  ])
  .action(billingDisable);
 
+ disable
+ .command("api-keys")
+ .aliases(["apikeys", "api_keys"])
+ .description("Disable API Keys on the linked instance")
+ .option(
+ "--for <targets...>",
+ "API Keys targets (orgs and/or users), separated by spaces or commas (e.g. orgs users). Omit to disable API Keys entirely.",
+ )
+ .option("--app <id>", "Application ID to target")
+ .option("--instance <id>", "Instance to target (dev, prod, or instance ID)")
+ .option("--yes", "Skip confirmation prompts")
+ .option("--dry-run", "Show the patch that would be sent without applying it")
+ .setExamples([
+ {
+ command: "clerk disable api-keys",
+ description: "Disable API Keys entirely",
+ },
+ {
+ command: "clerk disable api-keys --for orgs",
+ description: "Disable API Keys for organizations only",
+ },
+ {
+ command: "clerk disable api-keys --for users",
+ description: "Disable API Keys for users only",
+ },
+ ])
+ .action(apiKeysDisable);
+
  program
  .command("api")
  .description("Make authenticated requests to the Clerk API")

packages/cli-core/src/commands/api-keys/README.md

@@ -0,0 +1,52 @@
+# clerk api-keys (enable/disable)
+
+Toggle Clerk API Keys on the linked instance. The handlers are wired to
+top-level `clerk enable api-keys` and `clerk disable api-keys` commands.
+
+For arbitrary API Keys settings edits, use
+`clerk config patch --json '{"api_keys_settings":{...}}'`.
+
+## Usage
+
+```sh
+clerk enable api-keys [--for <targets>] [options]
+clerk disable api-keys [--for <targets>] [options]
+```
+
+`<targets>` is `orgs` and/or `users`, accepted as space-separated,
+comma-separated, or repeated `--for` flags. The singular aliases `org` and
+`user` are also accepted for backwards compatibility.
+
+```sh
+clerk enable api-keys # defaults to users
+clerk enable api-keys --for orgs users
+clerk enable api-keys --for orgs,users
+clerk disable api-keys # disables API Keys entirely
+clerk disable api-keys --for orgs # disables only organization API Keys
+```
+
+## Options
+
+| Flag | Description |
+| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
+| `--for <targets>` | Targets (`orgs` and/or `users`), separated by spaces or commas. Enable defaults to users; disable without `--for` disables API Keys entirely. |
+| `--app <id>` | Target a specific application |
+| `--instance <id>` | Target a specific instance (dev, prod) |
+| `--yes` | Skip the confirmation prompt |
+| `--dry-run` | Preview the patch without applying it |
+
+## Cascade behavior
+
+- `enable api-keys --for orgs` also sets `organization_settings.enabled = true`.
+ Organization API Keys require organizations enabled, so this saves a separate
+ command. The cascade is idempotent.
+- `disable api-keys --for orgs` disables only organization API Keys and leaves
+ organizations enabled.
+- `disable api-keys` without `--for` disables API Keys entirely.
+
+## Clerk API endpoints
+
+| Method | Endpoint | Description |
+| ------ | ----------------------------------------------------------------- | ----------------------------------------------------------------------- |
+| GET | `/v1/platform/applications/{appId}/instances/{instanceId}/config` | Fetch current config for diff before mutation |
+| PATCH | `/v1/platform/applications/{appId}/instances/{instanceId}/config` | Patch `api_keys_settings.*` (with `?dry_run=true` when `--dry-run` set) |

packages/cli-core/src/commands/api-keys/index.test.ts

@@ -0,0 +1,230 @@
+import { test, expect, describe, beforeEach, afterEach, spyOn, mock } from "bun:test";
+import { mkdtemp, rm } from "node:fs/promises";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { _setConfigDir, setProfile } from "../../lib/config.ts";
+import {
+ captureLog,
+ credentialStoreStubs,
+ gitStubs,
+ promptsStubs,
+ stubFetch,
+} from "../../test/lib/stubs.ts";
+
+mock.module("../../lib/credential-store.ts", () => credentialStoreStubs);
+mock.module("../../lib/git.ts", () => gitStubs);
+mock.module("@inquirer/prompts", () => promptsStubs);
+mock.module("../../lib/spinner.ts", () => ({
+ withSpinner: async (_msg: string, fn: () => Promise<unknown>) => fn(),
+}));
+
+describe("clerk enable/disable api-keys", () => {
+ const originalEnv = { ...process.env };
+ const originalFetch = globalThis.fetch;
+ let tempDir: string;
+ let logSpy: ReturnType<typeof spyOn>;
+ let errorSpy: ReturnType<typeof spyOn>;
+ let captured: ReturnType<typeof captureLog>;
+
+ beforeEach(async () => {
+ tempDir = await mkdtemp(join(tmpdir(), "clerk-api-keys-test-"));
+ _setConfigDir(tempDir);
+ process.env.CLERK_PLATFORM_API_KEY = "test_key";
+ process.env.CLERK_PLATFORM_API_URL = "https://test-api.clerk.com";
+
+ logSpy = spyOn(console, "log").mockImplementation(() => {});
+ errorSpy = spyOn(console, "error").mockImplementation(() => {});
+ captured = captureLog();
+
+ stubFetch(async () => {
+ return new Response(JSON.stringify({}), { status: 200 });
+ });
+ });
+
+ afterEach(async () => {
+ captured.teardown();
+ _setConfigDir(undefined);
+ process.env = { ...originalEnv };
+ globalThis.fetch = originalFetch;
+ logSpy.mockRestore();
+ errorSpy.mockRestore();
+ await rm(tempDir, { recursive: true, force: true });
+ });
+
+ async function setupProfile() {
+ await setProfile(process.cwd(), {
+ workspaceId: "org_1",
+ appId: "app_1",
+ instances: { development: "ins_dev" },
+ });
+ }
+
+ test("enable defaults to user API Keys", async () => {
+ let capturedBody = "";
+ stubFetch(async (_input, init) => {
+ if (init?.method === "PATCH") capturedBody = init.body as string;
+ return new Response(JSON.stringify({}), { status: 200 });
+ });
+
+ await setupProfile();
+ const { apiKeysEnable } = await import("./index.ts");
+ await captured.run(() => apiKeysEnable({}));
+
+ const parsed = JSON.parse(capturedBody);
+ expect(parsed.api_keys_settings.enabled).toBe(true);
+ expect(parsed.api_keys_settings.user_api_keys_enabled).toBe(true);
+ expect(parsed.api_keys_settings.orgs_api_keys_enabled).toBeUndefined();
+ expect(parsed.organization_settings).toBeUndefined();
+ });
+
+ test("enable --for orgs enables org API Keys and cascades organizations", async () => {
+ let capturedBody = "";
+ stubFetch(async (_input, init) => {
+ if (init?.method === "PATCH") capturedBody = init.body as string;
+ return new Response(JSON.stringify({}), { status: 200 });
+ });
+
+ await setupProfile();
+ const { apiKeysEnable } = await import("./index.ts");
+ await captured.run(() => apiKeysEnable({ for: ["orgs"] }));
+
+ const parsed = JSON.parse(capturedBody);
+ expect(parsed.api_keys_settings.enabled).toBe(true);
+ expect(parsed.api_keys_settings.orgs_api_keys_enabled).toBe(true);
+ expect(parsed.api_keys_settings.user_api_keys_enabled).toBeUndefined();
+ expect(parsed.organization_settings.enabled).toBe(true);
+ });
+
+ test("enable --for users,orgs sets both API Keys targets", async () => {
+ let capturedBody = "";
+ stubFetch(async (_input, init) => {
+ if (init?.method === "PATCH") capturedBody = init.body as string;
+ return new Response(JSON.stringify({}), { status: 200 });
+ });
+
+ await setupProfile();
+ const { apiKeysEnable } = await import("./index.ts");
+ await captured.run(() => apiKeysEnable({ for: ["users,orgs"] }));
+
+ const parsed = JSON.parse(capturedBody);
+ expect(parsed.api_keys_settings.user_api_keys_enabled).toBe(true);
+ expect(parsed.api_keys_settings.orgs_api_keys_enabled).toBe(true);
+ expect(parsed.organization_settings.enabled).toBe(true);
+ });
+
+ test("enable rejects invalid --for token", async () => {
+ await setupProfile();
+ const { apiKeysEnable } = await import("./index.ts");
+ await expect(captured.run(() => apiKeysEnable({ for: ["machine"] }))).rejects.toThrow(
+ 'Invalid --for value: "machine". Expected "orgs" and/or "users".',
+ );
+ });
+
+ test("enable accepts singular --for aliases", async () => {
+ let capturedBody = "";
+ stubFetch(async (_input, init) => {
+ if (init?.method === "PATCH") capturedBody = init.body as string;
+ return new Response(JSON.stringify({}), { status: 200 });
+ });
+
+ await setupProfile();
+ const { apiKeysEnable } = await import("./index.ts");
+ await captured.run(() => apiKeysEnable({ for: ["user", "org"] }));
+
+ const parsed = JSON.parse(capturedBody);
+ expect(parsed.api_keys_settings.user_api_keys_enabled).toBe(true);
+ expect(parsed.api_keys_settings.orgs_api_keys_enabled).toBe(true);
+ expect(parsed.organization_settings.enabled).toBe(true);
+ });
+
+ test("enable --dry-run plumbs dry_run=true to the API", async () => {
+ let capturedUrl = "";
+ stubFetch(async (input, init) => {
+ if (init?.method === "PATCH") capturedUrl = input.toString();
+ return new Response(JSON.stringify({}), { status: 200 });
+ });
+
+ await setupProfile();
+ const { apiKeysEnable } = await import("./index.ts");
+ await captured.run(() => apiKeysEnable({ dryRun: true }));
+
+ expect(capturedUrl).toContain("dry_run=true");
+ expect(captured.err).toContain("[dry-run]");
+ });
+
+ test("disable with no --for disables API Keys entirely", async () => {
+ let capturedBody = "";
+ stubFetch(async (_input, init) => {
+ if (init?.method === "PATCH") capturedBody = init.body as string;
+ return new Response(
+ JSON.stringify({
+ api_keys_settings: {
+ enabled: true,
+ user_api_keys_enabled: true,
+ orgs_api_keys_enabled: true,
+ },
+ }),
+ { status: 200 },
+ );
+ });
+
+ await setupProfile();
+ const { apiKeysDisable } = await import("./index.ts");
+ await captured.run(() => apiKeysDisable({}));
+
+ const parsed = JSON.parse(capturedBody);
+ expect(parsed.api_keys_settings.enabled).toBe(false);
+ expect(parsed.api_keys_settings.user_api_keys_enabled).toBe(false);
+ expect(parsed.api_keys_settings.orgs_api_keys_enabled).toBe(false);
+ });
+
+ test("disable --for orgs only disables org API Keys", async () => {
+ let capturedBody = "";
+ stubFetch(async (_input, init) => {
+ if (init?.method === "PATCH") capturedBody = init.body as string;
+ return new Response(
+ JSON.stringify({
+ api_keys_settings: {
+ enabled: true,
+ user_api_keys_enabled: true,
+ orgs_api_keys_enabled: true,
+ },
+ }),
+ { status: 200 },
+ );
+ });
+
+ await setupProfile();
+ const { apiKeysDisable } = await import("./index.ts");
+ await captured.run(() => apiKeysDisable({ for: ["orgs"] }));
+
+ const parsed = JSON.parse(capturedBody);
+ expect(parsed.api_keys_settings.enabled).toBeUndefined();
+ expect(parsed.api_keys_settings.user_api_keys_enabled).toBeUndefined();
+ expect(parsed.api_keys_settings.orgs_api_keys_enabled).toBe(false);
+ });
+
+ test("disable shows no changes when already fully disabled", async () => {
+ let patchCalls = 0;
+ stubFetch(async (_input, init) => {
+ if (init?.method === "PATCH") patchCalls++;
+ return new Response(
+ JSON.stringify({
+ api_keys_settings: {
+ enabled: false,
+ user_api_keys_enabled: false,
+ orgs_api_keys_enabled: false,
+ },
+ }),
+ { status: 200 },
+ );
+ });
+
+ await setupProfile();
+ const { apiKeysDisable } = await import("./index.ts");
+ await captured.run(() => apiKeysDisable({}));
+
+ expect(patchCalls).toBe(0);
+ expect(captured.err).toContain("No changes detected");
+ });
+});

.changeset/accept-orgs-users-for-flags.md

@@ -0,0 +1,5 @@
+---
+"clerk": minor
+---
+
+Add `clerk enable api-keys` and `clerk disable api-keys` for toggling API Keys on the linked instance. API Key targeting uses the canonical plural `orgs` and `users` values, while the singular `org` and `user` values continue to work as aliases.

packages/cli-core/src/cli-program.ts

@@ -48,6 +48,7 @@ import { update } from "./commands/update/index.ts";
 import { isClerkSkillInstalled } from "./lib/skill-detection.ts";
 import { orgsEnable, orgsDisable } from "./commands/orgs/index.ts";
 import { billingEnable, billingDisable } from "./commands/billing/index.ts";
+import { apiKeysEnable, apiKeysDisable } from "./commands/api-keys/index.ts";
 import { registerExtras } from "@clerk/cli-extras";
 
 const USER_LIST_ORDER_BY_FIELDS = [
@@ -636,6 +637,10 @@ Give AI agents better Clerk context: install the Clerk skills
  command: "clerk enable billing",
  description: "Enable billing for organizations and users",
  },
+ {
+ command: "clerk enable api-keys",
+ description: "Enable API Keys for users",
+ },
  ]);
 
  enable
@@ -703,6 +708,38 @@ Give AI agents better Clerk context: install the Clerk skills
  ])
  .action(billingEnable);
 
+ enable
+ .command("api-keys")
+ .aliases(["apikeys", "api_keys"])
+ .description("Enable API Keys on the linked instance")
+ .option(
+ "--for <targets...>",
+ "API Keys targets (orgs and/or users), separated by spaces or commas (e.g. orgs users). Defaults to users when omitted.",
+ )
+ .option("--app <id>", "Application ID to target")
+ .option("--instance <id>", "Instance to target (dev, prod, or instance ID)")
+ .option("--yes", "Skip confirmation prompts")
+ .option("--dry-run", "Show the patch that would be sent without applying it")
+ .setExamples([
+ {
+ command: "clerk enable api-keys",
+ description: "Enable API Keys for users",
+ },
+ {
+ command: "clerk enable api-keys --for orgs",
+ description: "Enable API Keys for organizations",
+ },
+ {
+ command: "clerk enable api-keys --for users orgs",
+ description: "Enable API Keys for users and organizations",
+ },
+ {
+ command: "clerk enable api-keys --dry-run",
+ description: "Preview the patch without applying it",
+ },
+ ])
+ .action(apiKeysEnable);
+
  const disable = program
  .command("disable")
  .description("Disable Clerk features on the linked instance")
@@ -716,6 +753,10 @@ Give AI agents better Clerk context: install the Clerk skills
  command: "clerk disable billing",
  description: "Disable billing for organizations and users",
  },
+ {
+ command: "clerk disable api-keys",
+ description: "Disable API Keys",
+ },
  ]);
 
  disable
@@ -764,6 +805,34 @@ Give AI agents better Clerk context: install the Clerk skills
  ])
  .action(billingDisable);
 
+ disable
+ .command("api-keys")
+ .aliases(["apikeys", "api_keys"])
+ .description("Disable API Keys on the linked instance")
+ .option(
+ "--for <targets...>",
+ "API Keys targets (orgs and/or users), separated by spaces or commas (e.g. orgs users). Omit to disable API Keys entirely.",
+ )
+ .option("--app <id>", "Application ID to target")
+ .option("--instance <id>", "Instance to target (dev, prod, or instance ID)")
+ .option("--yes", "Skip confirmation prompts")
+ .option("--dry-run", "Show the patch that would be sent without applying it")
+ .setExamples([
+ {
+ command: "clerk disable api-keys",
+ description: "Disable API Keys entirely",
+ },
+ {
+ command: "clerk disable api-keys --for orgs",
+ description: "Disable API Keys for organizations only",
+ },
+ {
+ command: "clerk disable api-keys --for users",
+ description: "Disable API Keys for users only",
+ },
+ ])
+ .action(apiKeysDisable);
+
  program
  .command("api")
  .description("Make authenticated requests to the Clerk API")

packages/cli-core/src/commands/api-keys/README.md

@@ -0,0 +1,52 @@
+# clerk api-keys (enable/disable)
+
+Toggle Clerk API Keys on the linked instance. The handlers are wired to
+top-level `clerk enable api-keys` and `clerk disable api-keys` commands.
+
+For arbitrary API Keys settings edits, use
+`clerk config patch --json '{"api_keys_settings":{...}}'`.
+
+## Usage
+
+```sh
+clerk enable api-keys [--for <targets>] [options]
+clerk disable api-keys [--for <targets>] [options]
+```
+
+`<targets>` is `orgs` and/or `users`, accepted as space-separated,
+comma-separated, or repeated `--for` flags. The singular aliases `org` and
+`user` are also accepted for backwards compatibility.
+
+```sh
+clerk enable api-keys # defaults to users
+clerk enable api-keys --for orgs users
+clerk enable api-keys --for orgs,users
+clerk disable api-keys # disables API Keys entirely
+clerk disable api-keys --for orgs # disables only organization API Keys
+```
+
+## Options
+
+| Flag | Description |
+| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
+| `--for <targets>` | Targets (`orgs` and/or `users`), separated by spaces or commas. Enable defaults to users; disable without `--for` disables API Keys entirely. |
+| `--app <id>` | Target a specific application |
+| `--instance <id>` | Target a specific instance (dev, prod) |
+| `--yes` | Skip the confirmation prompt |
+| `--dry-run` | Preview the patch without applying it |
+
+## Cascade behavior
+
+- `enable api-keys --for orgs` also sets `organization_settings.enabled = true`.
+ Organization API Keys require organizations enabled, so this saves a separate
+ command. The cascade is idempotent.
+- `disable api-keys --for orgs` disables only organization API Keys and leaves
+ organizations enabled.
+- `disable api-keys` without `--for` disables API Keys entirely.
+
+## Clerk API endpoints
+
+| Method | Endpoint | Description |
+| ------ | ----------------------------------------------------------------- | ----------------------------------------------------------------------- |
+| GET | `/v1/platform/applications/{appId}/instances/{instanceId}/config` | Fetch current config for diff before mutation |
+| PATCH | `/v1/platform/applications/{appId}/instances/{instanceId}/config` | Patch `api_keys_settings.*` (with `?dry_run=true` when `--dry-run` set) |

packages/cli-core/src/commands/api-keys/index.test.ts

@@ -0,0 +1,230 @@
+import { test, expect, describe, beforeEach, afterEach, spyOn, mock } from "bun:test";
+import { mkdtemp, rm } from "node:fs/promises";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { _setConfigDir, setProfile } from "../../lib/config.ts";
+import {
+ captureLog,
+ credentialStoreStubs,
+ gitStubs,
+ promptsStubs,
+ stubFetch,
+} from "../../test/lib/stubs.ts";
+
+mock.module("../../lib/credential-store.ts", () => credentialStoreStubs);
+mock.module("../../lib/git.ts", () => gitStubs);
+mock.module("@inquirer/prompts", () => promptsStubs);
+mock.module("../../lib/spinner.ts", () => ({
+ withSpinner: async (_msg: string, fn: () => Promise<unknown>) => fn(),
+}));
+
+describe("clerk enable/disable api-keys", () => {
+ const originalEnv = { ...process.env };
+ const originalFetch = globalThis.fetch;
+ let tempDir: string;
+ let logSpy: ReturnType<typeof spyOn>;
+ let errorSpy: ReturnType<typeof spyOn>;
+ let captured: ReturnType<typeof captureLog>;
+
+ beforeEach(async () => {
+ tempDir = await mkdtemp(join(tmpdir(), "clerk-api-keys-test-"));
+ _setConfigDir(tempDir);
+ process.env.CLERK_PLATFORM_API_KEY = "test_key";
+ process.env.CLERK_PLATFORM_API_URL = "https://test-api.clerk.com";
+
+ logSpy = spyOn(console, "log").mockImplementation(() => {});
+ errorSpy = spyOn(console, "error").mockImplementation(() => {});
+ captured = captureLog();
+
+ stubFetch(async () => {
+ return new Response(JSON.stringify({}), { status: 200 });
+ });
+ });
+
+ afterEach(async () => {
+ captured.teardown();
+ _setConfigDir(undefined);
+ process.env = { ...originalEnv };
+ globalThis.fetch = originalFetch;
+ logSpy.mockRestore();
+ errorSpy.mockRestore();
+ await rm(tempDir, { recursive: true, force: true });
+ });
+
+ async function setupProfile() {
+ await setProfile(process.cwd(), {
+ workspaceId: "org_1",
+ appId: "app_1",
+ instances: { development: "ins_dev" },
+ });
+ }
+
+ test("enable defaults to user API Keys", async () => {
+ let capturedBody = "";
+ stubFetch(async (_input, init) => {
+ if (init?.method === "PATCH") capturedBody = init.body as string;
+ return new Response(JSON.stringify({}), { status: 200 });
+ });
+
+ await setupProfile();
+ const { apiKeysEnable } = await import("./index.ts");
+ await captured.run(() => apiKeysEnable({}));
+
+ const parsed = JSON.parse(capturedBody);
+ expect(parsed.api_keys_settings.enabled).toBe(true);
+ expect(parsed.api_keys_settings.user_api_keys_enabled).toBe(true);
+ expect(parsed.api_keys_settings.orgs_api_keys_enabled).toBeUndefined();
+ expect(parsed.organization_settings).toBeUndefined();
+ });
+
+ test("enable --for orgs enables org API Keys and cascades organizations", async () => {
+ let capturedBody = "";
+ stubFetch(async (_input, init) => {
+ if (init?.method === "PATCH") capturedBody = init.body as string;
+ return new Response(JSON.stringify({}), { status: 200 });
+ });
+
+ await setupProfile();
+ const { apiKeysEnable } = await import("./index.ts");
+ await captured.run(() => apiKeysEnable({ for: ["orgs"] }));
+
+ const parsed = JSON.parse(capturedBody);
+ expect(parsed.api_keys_settings.enabled).toBe(true);
+ expect(parsed.api_keys_settings.orgs_api_keys_enabled).toBe(true);
+ expect(parsed.api_keys_settings.user_api_keys_enabled).toBeUndefined();
+ expect(parsed.organization_settings.enabled).toBe(true);
+ });
+
+ test("enable --for users,orgs sets both API Keys targets", async () => {
+ let capturedBody = "";
+ stubFetch(async (_input, init) => {
+ if (init?.method === "PATCH") capturedBody = init.body as string;
+ return new Response(JSON.stringify({}), { status: 200 });
+ });
+
+ await setupProfile();
+ const { apiKeysEnable } = await import("./index.ts");
+ await captured.run(() => apiKeysEnable({ for: ["users,orgs"] }));
+
+ const parsed = JSON.parse(capturedBody);
+ expect(parsed.api_keys_settings.user_api_keys_enabled).toBe(true);
+ expect(parsed.api_keys_settings.orgs_api_keys_enabled).toBe(true);
+ expect(parsed.organization_settings.enabled).toBe(true);
+ });
+
+ test("enable rejects invalid --for token", async () => {
+ await setupProfile();
+ const { apiKeysEnable } = await import("./index.ts");
+ await expect(captured.run(() => apiKeysEnable({ for: ["machine"] }))).rejects.toThrow(
+ 'Invalid --for value: "machine". Expected "orgs" and/or "users".',
+ );
+ });
+
+ test("enable accepts singular --for aliases", async () => {
+ let capturedBody = "";
+ stubFetch(async (_input, init) => {
+ if (init?.method === "PATCH") capturedBody = init.body as string;
+ return new Response(JSON.stringify({}), { status: 200 });
+ });
+
+ await setupProfile();
+ const { apiKeysEnable } = await import("./index.ts");
+ await captured.run(() => apiKeysEnable({ for: ["user", "org"] }));
+
+ const parsed = JSON.parse(capturedBody);
+ expect(parsed.api_keys_settings.user_api_keys_enabled).toBe(true);
+ expect(parsed.api_keys_settings.orgs_api_keys_enabled).toBe(true);
+ expect(parsed.organization_settings.enabled).toBe(true);
+ });
+
+ test("enable --dry-run plumbs dry_run=true to the API", async () => {
+ let capturedUrl = "";
+ stubFetch(async (input, init) => {
+ if (init?.method === "PATCH") capturedUrl = input.toString();
+ return new Response(JSON.stringify({}), { status: 200 });
+ });
+
+ await setupProfile();
+ const { apiKeysEnable } = await import("./index.ts");
+ await captured.run(() => apiKeysEnable({ dryRun: true }));
+
+ expect(capturedUrl).toContain("dry_run=true");
+ expect(captured.err).toContain("[dry-run]");
+ });
+
+ test("disable with no --for disables API Keys entirely", async () => {
+ let capturedBody = "";
+ stubFetch(async (_input, init) => {
+ if (init?.method === "PATCH") capturedBody = init.body as string;
+ return new Response(
+ JSON.stringify({
+ api_keys_settings: {
+ enabled: true,
+ user_api_keys_enabled: true,
+ orgs_api_keys_enabled: true,
+ },
+ }),
+ { status: 200 },
+ );
+ });
+
+ await setupProfile();
+ const { apiKeysDisable } = await import("./index.ts");
+ await captured.run(() => apiKeysDisable({}));
+
+ const parsed = JSON.parse(capturedBody);
+ expect(parsed.api_keys_settings.enabled).toBe(false);
+ expect(parsed.api_keys_settings.user_api_keys_enabled).toBe(false);
+ expect(parsed.api_keys_settings.orgs_api_keys_enabled).toBe(false);
+ });
+
+ test("disable --for orgs only disables org API Keys", async () => {
+ let capturedBody = "";
+ stubFetch(async (_input, init) => {
+ if (init?.method === "PATCH") capturedBody = init.body as string;
+ return new Response(
+ JSON.stringify({
+ api_keys_settings: {
+ enabled: true,
+ user_api_keys_enabled: true,
+ orgs_api_keys_enabled: true,
+ },
+ }),
+ { status: 200 },
+ );
+ });
+
+ await setupProfile();
+ const { apiKeysDisable } = await import("./index.ts");
+ await captured.run(() => apiKeysDisable({ for: ["orgs"] }));
+
+ const parsed = JSON.parse(capturedBody);
+ expect(parsed.api_keys_settings.enabled).toBeUndefined();
+ expect(parsed.api_keys_settings.user_api_keys_enabled).toBeUndefined();
+ expect(parsed.api_keys_settings.orgs_api_keys_enabled).toBe(false);
+ });
+
+ test("disable shows no changes when already fully disabled", async () => {
+ let patchCalls = 0;
+ stubFetch(async (_input, init) => {
+ if (init?.method === "PATCH") patchCalls++;
+ return new Response(
+ JSON.stringify({
+ api_keys_settings: {
+ enabled: false,
+ user_api_keys_enabled: false,
+ orgs_api_keys_enabled: false,
+ },
+ }),
+ { status: 200 },
+ );
+ });
+
+ await setupProfile();
+ const { apiKeysDisable } = await import("./index.ts");
+ await captured.run(() => apiKeysDisable({}));
+
+ expect(patchCalls).toBe(0);
+ expect(captured.err).toContain("No changes detected");
+ });
+});

.changeset/accept-orgs-users-for-flags.md

@@ -0,0 +1,5 @@
+---
+"clerk": minor
+---
+
+Add `clerk enable api-keys` and `clerk disable api-keys` for toggling API Keys on the linked instance. API Key targeting uses the canonical plural `orgs` and `users` values, while the singular `org` and `user` values continue to work as aliases.

packages/cli-core/src/cli-program.ts

@@ -48,6 +48,7 @@ import { update } from "./commands/update/index.ts";
 import { isClerkSkillInstalled } from "./lib/skill-detection.ts";
 import { orgsEnable, orgsDisable } from "./commands/orgs/index.ts";
 import { billingEnable, billingDisable } from "./commands/billing/index.ts";
+import { apiKeysEnable, apiKeysDisable } from "./commands/api-keys/index.ts";
 import { registerExtras } from "@clerk/cli-extras";
 
 const USER_LIST_ORDER_BY_FIELDS = [
@@ -636,6 +637,10 @@ Give AI agents better Clerk context: install the Clerk skills
  command: "clerk enable billing",
  description: "Enable billing for organizations and users",
  },
+ {
+ command: "clerk enable api-keys",
+ description: "Enable API Keys for users",
+ },
  ]);
 
  enable
@@ -703,6 +708,38 @@ Give AI agents better Clerk context: install the Clerk skills
  ])
  .action(billingEnable);
 
+ enable
+ .command("api-keys")
+ .aliases(["apikeys", "api_keys"])
+ .description("Enable API Keys on the linked instance")
+ .option(
+ "--for <targets...>",
+ "API Keys targets (orgs and/or users), separated by spaces or commas (e.g. orgs users). Defaults to users when omitted.",
+ )
+ .option("--app <id>", "Application ID to target")
+ .option("--instance <id>", "Instance to target (dev, prod, or instance ID)")
+ .option("--yes", "Skip confirmation prompts")
+ .option("--dry-run", "Show the patch that would be sent without applying it")
+ .setExamples([
+ {
+ command: "clerk enable api-keys",
+ description: "Enable API Keys for users",
+ },
+ {
+ command: "clerk enable api-keys --for orgs",
+ description: "Enable API Keys for organizations",
+ },
+ {
+ command: "clerk enable api-keys --for users orgs",
+ description: "Enable API Keys for users and organizations",
+ },
+ {
+ command: "clerk enable api-keys --dry-run",
+ description: "Preview the patch without applying it",
+ },
+ ])
+ .action(apiKeysEnable);
+
  const disable = program
  .command("disable")
  .description("Disable Clerk features on the linked instance")
@@ -716,6 +753,10 @@ Give AI agents better Clerk context: install the Clerk skills
  command: "clerk disable billing",
  description: "Disable billing for organizations and users",
  },
+ {
+ command: "clerk disable api-keys",
+ description: "Disable API Keys",
+ },
  ]);
 
  disable
@@ -764,6 +805,34 @@ Give AI agents better Clerk context: install the Clerk skills
  ])
  .action(billingDisable);
 
+ disable
+ .command("api-keys")
+ .aliases(["apikeys", "api_keys"])
+ .description("Disable API Keys on the linked instance")
+ .option(
+ "--for <targets...>",
+ "API Keys targets (orgs and/or users), separated by spaces or commas (e.g. orgs users). Omit to disable API Keys entirely.",
+ )
+ .option("--app <id>", "Application ID to target")
+ .option("--instance <id>", "Instance to target (dev, prod, or instance ID)")
+ .option("--yes", "Skip confirmation prompts")
+ .option("--dry-run", "Show the patch that would be sent without applying it")
+ .setExamples([
+ {
+ command: "clerk disable api-keys",
+ description: "Disable API Keys entirely",
+ },
+ {
+ command: "clerk disable api-keys --for orgs",
+ description: "Disable API Keys for organizations only",
+ },
+ {
+ command: "clerk disable api-keys --for users",
+ description: "Disable API Keys for users only",
+ },
+ ])
+ .action(apiKeysDisable);
+
  program
  .command("api")
  .description("Make authenticated requests to the Clerk API")

packages/cli-core/src/commands/api-keys/README.md

@@ -0,0 +1,52 @@
+# clerk api-keys (enable/disable)
+
+Toggle Clerk API Keys on the linked instance. The handlers are wired to
+top-level `clerk enable api-keys` and `clerk disable api-keys` commands.
+
+For arbitrary API Keys settings edits, use
+`clerk config patch --json '{"api_keys_settings":{...}}'`.
+
+## Usage
+
+```sh
+clerk enable api-keys [--for <targets>] [options]
+clerk disable api-keys [--for <targets>] [options]
+```
+
+`<targets>` is `orgs` and/or `users`, accepted as space-separated,
+comma-separated, or repeated `--for` flags. The singular aliases `org` and
+`user` are also accepted for backwards compatibility.
+
+```sh
+clerk enable api-keys # defaults to users
+clerk enable api-keys --for orgs users
+clerk enable api-keys --for orgs,users
+clerk disable api-keys # disables API Keys entirely
+clerk disable api-keys --for orgs # disables only organization API Keys
+```
+
+## Options
+
+| Flag | Description |
+| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
+| `--for <targets>` | Targets (`orgs` and/or `users`), separated by spaces or commas. Enable defaults to users; disable without `--for` disables API Keys entirely. |
+| `--app <id>` | Target a specific application |
+| `--instance <id>` | Target a specific instance (dev, prod) |
+| `--yes` | Skip the confirmation prompt |
+| `--dry-run` | Preview the patch without applying it |
+
+## Cascade behavior
+
+- `enable api-keys --for orgs` also sets `organization_settings.enabled = true`.
+ Organization API Keys require organizations enabled, so this saves a separate
+ command. The cascade is idempotent.
+- `disable api-keys --for orgs` disables only organization API Keys and leaves
+ organizations enabled.
+- `disable api-keys` without `--for` disables API Keys entirely.
+
+## Clerk API endpoints
+
+| Method | Endpoint | Description |
+| ------ | ----------------------------------------------------------------- | ----------------------------------------------------------------------- |
+| GET | `/v1/platform/applications/{appId}/instances/{instanceId}/config` | Fetch current config for diff before mutation |
+| PATCH | `/v1/platform/applications/{appId}/instances/{instanceId}/config` | Patch `api_keys_settings.*` (with `?dry_run=true` when `--dry-run` set) |

packages/cli-core/src/commands/api-keys/index.test.ts

@@ -0,0 +1,230 @@
+import { test, expect, describe, beforeEach, afterEach, spyOn, mock } from "bun:test";
+import { mkdtemp, rm } from "node:fs/promises";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { _setConfigDir, setProfile } from "../../lib/config.ts";
+import {
+ captureLog,
+ credentialStoreStubs,
+ gitStubs,
+ promptsStubs,
+ stubFetch,
+} from "../../test/lib/stubs.ts";
+
+mock.module("../../lib/credential-store.ts", () => credentialStoreStubs);
+mock.module("../../lib/git.ts", () => gitStubs);
+mock.module("@inquirer/prompts", () => promptsStubs);
+mock.module("../../lib/spinner.ts", () => ({
+ withSpinner: async (_msg: string, fn: () => Promise<unknown>) => fn(),
+}));
+
+describe("clerk enable/disable api-keys", () => {
+ const originalEnv = { ...process.env };
+ const originalFetch = globalThis.fetch;
+ let tempDir: string;
+ let logSpy: ReturnType<typeof spyOn>;
+ let errorSpy: ReturnType<typeof spyOn>;
+ let captured: ReturnType<typeof captureLog>;
+
+ beforeEach(async () => {
+ tempDir = await mkdtemp(join(tmpdir(), "clerk-api-keys-test-"));
+ _setConfigDir(tempDir);
+ process.env.CLERK_PLATFORM_API_KEY = "test_key";
+ process.env.CLERK_PLATFORM_API_URL = "https://test-api.clerk.com";
+
+ logSpy = spyOn(console, "log").mockImplementation(() => {});
+ errorSpy = spyOn(console, "error").mockImplementation(() => {});
+ captured = captureLog();
+
+ stubFetch(async () => {
+ return new Response(JSON.stringify({}), { status: 200 });
+ });
+ });
+
+ afterEach(async () => {
+ captured.teardown();
+ _setConfigDir(undefined);
+ process.env = { ...originalEnv };
+ globalThis.fetch = originalFetch;
+ logSpy.mockRestore();
+ errorSpy.mockRestore();
+ await rm(tempDir, { recursive: true, force: true });
+ });
+
+ async function setupProfile() {
+ await setProfile(process.cwd(), {
+ workspaceId: "org_1",
+ appId: "app_1",
+ instances: { development: "ins_dev" },
+ });
+ }
+
+ test("enable defaults to user API Keys", async () => {
+ let capturedBody = "";
+ stubFetch(async (_input, init) => {
+ if (init?.method === "PATCH") capturedBody = init.body as string;
+ return new Response(JSON.stringify({}), { status: 200 });
+ });
+
+ await setupProfile();
+ const { apiKeysEnable } = await import("./index.ts");
+ await captured.run(() => apiKeysEnable({}));
+
+ const parsed = JSON.parse(capturedBody);
+ expect(parsed.api_keys_settings.enabled).toBe(true);
+ expect(parsed.api_keys_settings.user_api_keys_enabled).toBe(true);
+ expect(parsed.api_keys_settings.orgs_api_keys_enabled).toBeUndefined();
+ expect(parsed.organization_settings).toBeUndefined();
+ });
+
+ test("enable --for orgs enables org API Keys and cascades organizations", async () => {
+ let capturedBody = "";
+ stubFetch(async (_input, init) => {
+ if (init?.method === "PATCH") capturedBody = init.body as string;
+ return new Response(JSON.stringify({}), { status: 200 });
+ });
+
+ await setupProfile();
+ const { apiKeysEnable } = await import("./index.ts");
+ await captured.run(() => apiKeysEnable({ for: ["orgs"] }));
+
+ const parsed = JSON.parse(capturedBody);
+ expect(parsed.api_keys_settings.enabled).toBe(true);
+ expect(parsed.api_keys_settings.orgs_api_keys_enabled).toBe(true);
+ expect(parsed.api_keys_settings.user_api_keys_enabled).toBeUndefined();
+ expect(parsed.organization_settings.enabled).toBe(true);
+ });
+
+ test("enable --for users,orgs sets both API Keys targets", async () => {
+ let capturedBody = "";
+ stubFetch(async (_input, init) => {
+ if (init?.method === "PATCH") capturedBody = init.body as string;
+ return new Response(JSON.stringify({}), { status: 200 });
+ });
+
+ await setupProfile();
+ const { apiKeysEnable } = await import("./index.ts");
+ await captured.run(() => apiKeysEnable({ for: ["users,orgs"] }));
+
+ const parsed = JSON.parse(capturedBody);
+ expect(parsed.api_keys_settings.user_api_keys_enabled).toBe(true);
+ expect(parsed.api_keys_settings.orgs_api_keys_enabled).toBe(true);
+ expect(parsed.organization_settings.enabled).toBe(true);
+ });
+
+ test("enable rejects invalid --for token", async () => {
+ await setupProfile();
+ const { apiKeysEnable } = await import("./index.ts");
+ await expect(captured.run(() => apiKeysEnable({ for: ["machine"] }))).rejects.toThrow(
+ 'Invalid --for value: "machine". Expected "orgs" and/or "users".',
+ );
+ });
+
+ test("enable accepts singular --for aliases", async () => {
+ let capturedBody = "";
+ stubFetch(async (_input, init) => {
+ if (init?.method === "PATCH") capturedBody = init.body as string;
+ return new Response(JSON.stringify({}), { status: 200 });
+ });
+
+ await setupProfile();
+ const { apiKeysEnable } = await import("./index.ts");
+ await captured.run(() => apiKeysEnable({ for: ["user", "org"] }));
+
+ const parsed = JSON.parse(capturedBody);
+ expect(parsed.api_keys_settings.user_api_keys_enabled).toBe(true);
+ expect(parsed.api_keys_settings.orgs_api_keys_enabled).toBe(true);
+ expect(parsed.organization_settings.enabled).toBe(true);
+ });
+
+ test("enable --dry-run plumbs dry_run=true to the API", async () => {
+ let capturedUrl = "";
+ stubFetch(async (input, init) => {
+ if (init?.method === "PATCH") capturedUrl = input.toString();
+ return new Response(JSON.stringify({}), { status: 200 });
+ });
+
+ await setupProfile();
+ const { apiKeysEnable } = await import("./index.ts");
+ await captured.run(() => apiKeysEnable({ dryRun: true }));
+
+ expect(capturedUrl).toContain("dry_run=true");
+ expect(captured.err).toContain("[dry-run]");
+ });
+
+ test("disable with no --for disables API Keys entirely", async () => {
+ let capturedBody = "";
+ stubFetch(async (_input, init) => {
+ if (init?.method === "PATCH") capturedBody = init.body as string;
+ return new Response(
+ JSON.stringify({
+ api_keys_settings: {
+ enabled: true,
+ user_api_keys_enabled: true,
+ orgs_api_keys_enabled: true,
+ },
+ }),
+ { status: 200 },
+ );
+ });
+
+ await setupProfile();
+ const { apiKeysDisable } = await import("./index.ts");
+ await captured.run(() => apiKeysDisable({}));
+
+ const parsed = JSON.parse(capturedBody);
+ expect(parsed.api_keys_settings.enabled).toBe(false);
+ expect(parsed.api_keys_settings.user_api_keys_enabled).toBe(false);
+ expect(parsed.api_keys_settings.orgs_api_keys_enabled).toBe(false);
+ });
+
+ test("disable --for orgs only disables org API Keys", async () => {
+ let capturedBody = "";
+ stubFetch(async (_input, init) => {
+ if (init?.method === "PATCH") capturedBody = init.body as string;
+ return new Response(
+ JSON.stringify({
+ api_keys_settings: {
+ enabled: true,
+ user_api_keys_enabled: true,
+ orgs_api_keys_enabled: true,
+ },
+ }),
+ { status: 200 },
+ );
+ });
+
+ await setupProfile();
+ const { apiKeysDisable } = await import("./index.ts");
+ await captured.run(() => apiKeysDisable({ for: ["orgs"] }));
+
+ const parsed = JSON.parse(capturedBody);
+ expect(parsed.api_keys_settings.enabled).toBeUndefined();
+ expect(parsed.api_keys_settings.user_api_keys_enabled).toBeUndefined();
+ expect(parsed.api_keys_settings.orgs_api_keys_enabled).toBe(false);
+ });
+
+ test("disable shows no changes when already fully disabled", async () => {
+ let patchCalls = 0;
+ stubFetch(async (_input, init) => {
+ if (init?.method === "PATCH") patchCalls++;
+ return new Response(
+ JSON.stringify({
+ api_keys_settings: {
+ enabled: false,
+ user_api_keys_enabled: false,
+ orgs_api_keys_enabled: false,
+ },
+ }),
+ { status: 200 },
+ );
+ });
+
+ await setupProfile();
+ const { apiKeysDisable } = await import("./index.ts");
+ await captured.run(() => apiKeysDisable({}));
+
+ expect(patchCalls).toBe(0);
+ expect(captured.err).toContain("No changes detected");
+ });
+});

.changeset/accept-orgs-users-for-flags.md

@@ -0,0 +1,5 @@
+---
+"clerk": minor
+---
+
+Add `clerk enable api-keys` and `clerk disable api-keys` for toggling API Keys on the linked instance. API Key targeting uses the canonical plural `orgs` and `users` values, while the singular `org` and `user` values continue to work as aliases.

packages/cli-core/src/cli-program.ts

@@ -48,6 +48,7 @@ import { update } from "./commands/update/index.ts";
 import { isClerkSkillInstalled } from "./lib/skill-detection.ts";
 import { orgsEnable, orgsDisable } from "./commands/orgs/index.ts";
 import { billingEnable, billingDisable } from "./commands/billing/index.ts";
+import { apiKeysEnable, apiKeysDisable } from "./commands/api-keys/index.ts";
 import { registerExtras } from "@clerk/cli-extras";
 
 const USER_LIST_ORDER_BY_FIELDS = [
@@ -636,6 +637,10 @@ Give AI agents better Clerk context: install the Clerk skills
  command: "clerk enable billing",
  description: "Enable billing for organizations and users",
  },
+ {
+ command: "clerk enable api-keys",
+ description: "Enable API Keys for users",
+ },
  ]);
 
  enable
@@ -703,6 +708,38 @@ Give AI agents better Clerk context: install the Clerk skills
  ])
  .action(billingEnable);
 
+ enable
+ .command("api-keys")
+ .aliases(["apikeys", "api_keys"])
+ .description("Enable API Keys on the linked instance")
+ .option(
+ "--for <targets...>",
+ "API Keys targets (orgs and/or users), separated by spaces or commas (e.g. orgs users). Defaults to users when omitted.",
+ )
+ .option("--app <id>", "Application ID to target")
+ .option("--instance <id>", "Instance to target (dev, prod, or instance ID)")
+ .option("--yes", "Skip confirmation prompts")
+ .option("--dry-run", "Show the patch that would be sent without applying it")
+ .setExamples([
+ {
+ command: "clerk enable api-keys",
+ description: "Enable API Keys for users",
+ },
+ {
+ command: "clerk enable api-keys --for orgs",
+ description: "Enable API Keys for organizations",
+ },
+ {
+ command: "clerk enable api-keys --for users orgs",
+ description: "Enable API Keys for users and organizations",
+ },
+ {
+ command: "clerk enable api-keys --dry-run",
+ description: "Preview the patch without applying it",
+ },
+ ])
+ .action(apiKeysEnable);
+
  const disable = program
  .command("disable")
  .description("Disable Clerk features on the linked instance")
@@ -716,6 +753,10 @@ Give AI agents better Clerk context: install the Clerk skills
  command: "clerk disable billing",
  description: "Disable billing for organizations and users",
  },
+ {
+ command: "clerk disable api-keys",
+ description: "Disable API Keys",
+ },
  ]);
 
  disable
@@ -764,6 +805,34 @@ Give AI agents better Clerk context: install the Clerk skills
  ])
  .action(billingDisable);
 
+ disable
+ .command("api-keys")
+ .aliases(["apikeys", "api_keys"])
+ .description("Disable API Keys on the linked instance")
+ .option(
+ "--for <targets...>",
+ "API Keys targets (orgs and/or users), separated by spaces or commas (e.g. orgs users). Omit to disable API Keys entirely.",
+ )
+ .option("--app <id>", "Application ID to target")
+ .option("--instance <id>", "Instance to target (dev, prod, or instance ID)")
+ .option("--yes", "Skip confirmation prompts")
+ .option("--dry-run", "Show the patch that would be sent without applying it")
+ .setExamples([
+ {
+ command: "clerk disable api-keys",
+ description: "Disable API Keys entirely",
+ },
+ {
+ command: "clerk disable api-keys --for orgs",
+ description: "Disable API Keys for organizations only",
+ },
+ {
+ command: "clerk disable api-keys --for users",
+ description: "Disable API Keys for users only",
+ },
+ ])
+ .action(apiKeysDisable);
+
  program
  .command("api")
  .description("Make authenticated requests to the Clerk API")

packages/cli-core/src/commands/api-keys/README.md

@@ -0,0 +1,52 @@
+# clerk api-keys (enable/disable)
+
+Toggle Clerk API Keys on the linked instance. The handlers are wired to
+top-level `clerk enable api-keys` and `clerk disable api-keys` commands.
+
+For arbitrary API Keys settings edits, use
+`clerk config patch --json '{"api_keys_settings":{...}}'`.
+
+## Usage
+
+```sh
+clerk enable api-keys [--for <targets>] [options]
+clerk disable api-keys [--for <targets>] [options]
+```
+
+`<targets>` is `orgs` and/or `users`, accepted as space-separated,
+comma-separated, or repeated `--for` flags. The singular aliases `org` and
+`user` are also accepted for backwards compatibility.
+
+```sh
+clerk enable api-keys # defaults to users
+clerk enable api-keys --for orgs users
+clerk enable api-keys --for orgs,users
+clerk disable api-keys # disables API Keys entirely
+clerk disable api-keys --for orgs # disables only organization API Keys
+```
+
+## Options
+
+| Flag | Description |
+| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
+| `--for <targets>` | Targets (`orgs` and/or `users`), separated by spaces or commas. Enable defaults to users; disable without `--for` disables API Keys entirely. |
+| `--app <id>` | Target a specific application |
+| `--instance <id>` | Target a specific instance (dev, prod) |
+| `--yes` | Skip the confirmation prompt |
+| `--dry-run` | Preview the patch without applying it |
+
+## Cascade behavior
+
+- `enable api-keys --for orgs` also sets `organization_settings.enabled = true`.
+ Organization API Keys require organizations enabled, so this saves a separate
+ command. The cascade is idempotent.
+- `disable api-keys --for orgs` disables only organization API Keys and leaves
+ organizations enabled.
+- `disable api-keys` without `--for` disables API Keys entirely.
+
+## Clerk API endpoints
+
+| Method | Endpoint | Description |
+| ------ | ----------------------------------------------------------------- | ----------------------------------------------------------------------- |
+| GET | `/v1/platform/applications/{appId}/instances/{instanceId}/config` | Fetch current config for diff before mutation |
+| PATCH | `/v1/platform/applications/{appId}/instances/{instanceId}/config` | Patch `api_keys_settings.*` (with `?dry_run=true` when `--dry-run` set) |

packages/cli-core/src/commands/api-keys/index.test.ts

@@ -0,0 +1,230 @@
+import { test, expect, describe, beforeEach, afterEach, spyOn, mock } from "bun:test";
+import { mkdtemp, rm } from "node:fs/promises";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { _setConfigDir, setProfile } from "../../lib/config.ts";
+import {
+ captureLog,
+ credentialStoreStubs,
+ gitStubs,
+ promptsStubs,
+ stubFetch,
+} from "../../test/lib/stubs.ts";
+
+mock.module("../../lib/credential-store.ts", () => credentialStoreStubs);
+mock.module("../../lib/git.ts", () => gitStubs);
+mock.module("@inquirer/prompts", () => promptsStubs);
+mock.module("../../lib/spinner.ts", () => ({
+ withSpinner: async (_msg: string, fn: () => Promise<unknown>) => fn(),
+}));
+
+describe("clerk enable/disable api-keys", () => {
+ const originalEnv = { ...process.env };
+ const originalFetch = globalThis.fetch;
+ let tempDir: string;
+ let logSpy: ReturnType<typeof spyOn>;
+ let errorSpy: ReturnType<typeof spyOn>;
+ let captured: ReturnType<typeof captureLog>;
+
+ beforeEach(async () => {
+ tempDir = await mkdtemp(join(tmpdir(), "clerk-api-keys-test-"));
+ _setConfigDir(tempDir);
+ process.env.CLERK_PLATFORM_API_KEY = "test_key";
+ process.env.CLERK_PLATFORM_API_URL = "https://test-api.clerk.com";
+
+ logSpy = spyOn(console, "log").mockImplementation(() => {});
+ errorSpy = spyOn(console, "error").mockImplementation(() => {});
+ captured = captureLog();
+
+ stubFetch(async () => {
+ return new Response(JSON.stringify({}), { status: 200 });
+ });
+ });
+
+ afterEach(async () => {
+ captured.teardown();
+ _setConfigDir(undefined);
+ process.env = { ...originalEnv };
+ globalThis.fetch = originalFetch;
+ logSpy.mockRestore();
+ errorSpy.mockRestore();
+ await rm(tempDir, { recursive: true, force: true });
+ });
+
+ async function setupProfile() {
+ await setProfile(process.cwd(), {
+ workspaceId: "org_1",
+ appId: "app_1",
+ instances: { development: "ins_dev" },
+ });
+ }
+
+ test("enable defaults to user API Keys", async () => {
+ let capturedBody = "";
+ stubFetch(async (_input, init) => {
+ if (init?.method === "PATCH") capturedBody = init.body as string;
+ return new Response(JSON.stringify({}), { status: 200 });
+ });
+
+ await setupProfile();
+ const { apiKeysEnable } = await import("./index.ts");
+ await captured.run(() => apiKeysEnable({}));
+
+ const parsed = JSON.parse(capturedBody);
+ expect(parsed.api_keys_settings.enabled).toBe(true);
+ expect(parsed.api_keys_settings.user_api_keys_enabled).toBe(true);
+ expect(parsed.api_keys_settings.orgs_api_keys_enabled).toBeUndefined();
+ expect(parsed.organization_settings).toBeUndefined();
+ });
+
+ test("enable --for orgs enables org API Keys and cascades organizations", async () => {
+ let capturedBody = "";
+ stubFetch(async (_input, init) => {
+ if (init?.method === "PATCH") capturedBody = init.body as string;
+ return new Response(JSON.stringify({}), { status: 200 });
+ });
+
+ await setupProfile();
+ const { apiKeysEnable } = await import("./index.ts");
+ await captured.run(() => apiKeysEnable({ for: ["orgs"] }));
+
+ const parsed = JSON.parse(capturedBody);
+ expect(parsed.api_keys_settings.enabled).toBe(true);
+ expect(parsed.api_keys_settings.orgs_api_keys_enabled).toBe(true);
+ expect(parsed.api_keys_settings.user_api_keys_enabled).toBeUndefined();
+ expect(parsed.organization_settings.enabled).toBe(true);
+ });
+
+ test("enable --for users,orgs sets both API Keys targets", async () => {
+ let capturedBody = "";
+ stubFetch(async (_input, init) => {
+ if (init?.method === "PATCH") capturedBody = init.body as string;
+ return new Response(JSON.stringify({}), { status: 200 });
+ });
+
+ await setupProfile();
+ const { apiKeysEnable } = await import("./index.ts");
+ await captured.run(() => apiKeysEnable({ for: ["users,orgs"] }));
+
+ const parsed = JSON.parse(capturedBody);
+ expect(parsed.api_keys_settings.user_api_keys_enabled).toBe(true);
+ expect(parsed.api_keys_settings.orgs_api_keys_enabled).toBe(true);
+ expect(parsed.organization_settings.enabled).toBe(true);
+ });
+
+ test("enable rejects invalid --for token", async () => {
+ await setupProfile();
+ const { apiKeysEnable } = await import("./index.ts");
+ await expect(captured.run(() => apiKeysEnable({ for: ["machine"] }))).rejects.toThrow(
+ 'Invalid --for value: "machine". Expected "orgs" and/or "users".',
+ );
+ });
+
+ test("enable accepts singular --for aliases", async () => {
+ let capturedBody = "";
+ stubFetch(async (_input, init) => {
+ if (init?.method === "PATCH") capturedBody = init.body as string;
+ return new Response(JSON.stringify({}), { status: 200 });
+ });
+
+ await setupProfile();
+ const { apiKeysEnable } = await import("./index.ts");
+ await captured.run(() => apiKeysEnable({ for: ["user", "org"] }));
+
+ const parsed = JSON.parse(capturedBody);
+ expect(parsed.api_keys_settings.user_api_keys_enabled).toBe(true);
+ expect(parsed.api_keys_settings.orgs_api_keys_enabled).toBe(true);
+ expect(parsed.organization_settings.enabled).toBe(true);
+ });
+
+ test("enable --dry-run plumbs dry_run=true to the API", async () => {
+ let capturedUrl = "";
+ stubFetch(async (input, init) => {
+ if (init?.method === "PATCH") capturedUrl = input.toString();
+ return new Response(JSON.stringify({}), { status: 200 });
+ });
+
+ await setupProfile();
+ const { apiKeysEnable } = await import("./index.ts");
+ await captured.run(() => apiKeysEnable({ dryRun: true }));
+
+ expect(capturedUrl).toContain("dry_run=true");
+ expect(captured.err).toContain("[dry-run]");
+ });
+
+ test("disable with no --for disables API Keys entirely", async () => {
+ let capturedBody = "";
+ stubFetch(async (_input, init) => {
+ if (init?.method === "PATCH") capturedBody = init.body as string;
+ return new Response(
+ JSON.stringify({
+ api_keys_settings: {
+ enabled: true,
+ user_api_keys_enabled: true,
+ orgs_api_keys_enabled: true,
+ },
+ }),
+ { status: 200 },
+ );
+ });
+
+ await setupProfile();
+ const { apiKeysDisable } = await import("./index.ts");
+ await captured.run(() => apiKeysDisable({}));
+
+ const parsed = JSON.parse(capturedBody);
+ expect(parsed.api_keys_settings.enabled).toBe(false);
+ expect(parsed.api_keys_settings.user_api_keys_enabled).toBe(false);
+ expect(parsed.api_keys_settings.orgs_api_keys_enabled).toBe(false);
+ });
+
+ test("disable --for orgs only disables org API Keys", async () => {
+ let capturedBody = "";
+ stubFetch(async (_input, init) => {
+ if (init?.method === "PATCH") capturedBody = init.body as string;
+ return new Response(
+ JSON.stringify({
+ api_keys_settings: {
+ enabled: true,
+ user_api_keys_enabled: true,
+ orgs_api_keys_enabled: true,
+ },
+ }),
+ { status: 200 },
+ );
+ });
+
+ await setupProfile();
+ const { apiKeysDisable } = await import("./index.ts");
+ await captured.run(() => apiKeysDisable({ for: ["orgs"] }));
+
+ const parsed = JSON.parse(capturedBody);
+ expect(parsed.api_keys_settings.enabled).toBeUndefined();
+ expect(parsed.api_keys_settings.user_api_keys_enabled).toBeUndefined();
+ expect(parsed.api_keys_settings.orgs_api_keys_enabled).toBe(false);
+ });
+
+ test("disable shows no changes when already fully disabled", async () => {
+ let patchCalls = 0;
+ stubFetch(async (_input, init) => {
+ if (init?.method === "PATCH") patchCalls++;
+ return new Response(
+ JSON.stringify({
+ api_keys_settings: {
+ enabled: false,
+ user_api_keys_enabled: false,
+ orgs_api_keys_enabled: false,
+ },
+ }),
+ { status: 200 },
+ );
+ });
+
+ await setupProfile();
+ const { apiKeysDisable } = await import("./index.ts");
+ await captured.run(() => apiKeysDisable({}));
+
+ expect(patchCalls).toBe(0);
+ expect(captured.err).toContain("No changes detected");
+ });
+});

.changeset/accept-orgs-users-for-flags.md

@@ -0,0 +1,5 @@
+---
+"clerk": minor
+---
+
+Add `clerk enable api-keys` and `clerk disable api-keys` for toggling API Keys on the linked instance. API Key targeting uses the canonical plural `orgs` and `users` values, while the singular `org` and `user` values continue to work as aliases.

packages/cli-core/src/cli-program.ts

@@ -48,6 +48,7 @@ import { update } from "./commands/update/index.ts";
 import { isClerkSkillInstalled } from "./lib/skill-detection.ts";
 import { orgsEnable, orgsDisable } from "./commands/orgs/index.ts";
 import { billingEnable, billingDisable } from "./commands/billing/index.ts";
+import { apiKeysEnable, apiKeysDisable } from "./commands/api-keys/index.ts";
 import { registerExtras } from "@clerk/cli-extras";
 
 const USER_LIST_ORDER_BY_FIELDS = [
@@ -636,6 +637,10 @@ Give AI agents better Clerk context: install the Clerk skills
  command: "clerk enable billing",
  description: "Enable billing for organizations and users",
  },
+ {
+ command: "clerk enable api-keys",
+ description: "Enable API Keys for users",
+ },
  ]);
 
  enable
@@ -703,6 +708,38 @@ Give AI agents better Clerk context: install the Clerk skills
  ])
  .action(billingEnable);
 
+ enable
+ .command("api-keys")
+ .aliases(["apikeys", "api_keys"])
+ .description("Enable API Keys on the linked instance")
+ .option(
+ "--for <targets...>",
+ "API Keys targets (orgs and/or users), separated by spaces or commas (e.g. orgs users). Defaults to users when omitted.",
+ )
+ .option("--app <id>", "Application ID to target")
+ .option("--instance <id>", "Instance to target (dev, prod, or instance ID)")
+ .option("--yes", "Skip confirmation prompts")
+ .option("--dry-run", "Show the patch that would be sent without applying it")
+ .setExamples([
+ {
+ command: "clerk enable api-keys",
+ description: "Enable API Keys for users",
+ },
+ {
+ command: "clerk enable api-keys --for orgs",
+ description: "Enable API Keys for organizations",
+ },
+ {
+ command: "clerk enable api-keys --for users orgs",
+ description: "Enable API Keys for users and organizations",
+ },
+ {
+ command: "clerk enable api-keys --dry-run",
+ description: "Preview the patch without applying it",
+ },
+ ])
+ .action(apiKeysEnable);
+
  const disable = program
  .command("disable")
  .description("Disable Clerk features on the linked instance")
@@ -716,6 +753,10 @@ Give AI agents better Clerk context: install the Clerk skills
  command: "clerk disable billing",
  description: "Disable billing for organizations and users",
  },
+ {
+ command: "clerk disable api-keys",
+ description: "Disable API Keys",
+ },
  ]);
 
  disable
@@ -764,6 +805,34 @@ Give AI agents better Clerk context: install the Clerk skills
  ])
  .action(billingDisable);
 
+ disable
+ .command("api-keys")
+ .aliases(["apikeys", "api_keys"])
+ .description("Disable API Keys on the linked instance")
+ .option(
+ "--for <targets...>",
+ "API Keys targets (orgs and/or users), separated by spaces or commas (e.g. orgs users). Omit to disable API Keys entirely.",
+ )
+ .option("--app <id>", "Application ID to target")
+ .option("--instance <id>", "Instance to target (dev, prod, or instance ID)")
+ .option("--yes", "Skip confirmation prompts")
+ .option("--dry-run", "Show the patch that would be sent without applying it")
+ .setExamples([
+ {
+ command: "clerk disable api-keys",
+ description: "Disable API Keys entirely",
+ },
+ {
+ command: "clerk disable api-keys --for orgs",
+ description: "Disable API Keys for organizations only",
+ },
+ {
+ command: "clerk disable api-keys --for users",
+ description: "Disable API Keys for users only",
+ },
+ ])
+ .action(apiKeysDisable);
+
  program
  .command("api")
  .description("Make authenticated requests to the Clerk API")

packages/cli-core/src/commands/api-keys/README.md

@@ -0,0 +1,52 @@
+# clerk api-keys (enable/disable)
+
+Toggle Clerk API Keys on the linked instance. The handlers are wired to
+top-level `clerk enable api-keys` and `clerk disable api-keys` commands.
+
+For arbitrary API Keys settings edits, use
+`clerk config patch --json '{"api_keys_settings":{...}}'`.
+
+## Usage
+
+```sh
+clerk enable api-keys [--for <targets>] [options]
+clerk disable api-keys [--for <targets>] [options]
+```
+
+`<targets>` is `orgs` and/or `users`, accepted as space-separated,
+comma-separated, or repeated `--for` flags. The singular aliases `org` and
+`user` are also accepted for backwards compatibility.
+
+```sh
+clerk enable api-keys # defaults to users
+clerk enable api-keys --for orgs users
+clerk enable api-keys --for orgs,users
+clerk disable api-keys # disables API Keys entirely
+clerk disable api-keys --for orgs # disables only organization API Keys
+```
+
+## Options
+
+| Flag | Description |
+| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
+| `--for <targets>` | Targets (`orgs` and/or `users`), separated by spaces or commas. Enable defaults to users; disable without `--for` disables API Keys entirely. |
+| `--app <id>` | Target a specific application |
+| `--instance <id>` | Target a specific instance (dev, prod) |
+| `--yes` | Skip the confirmation prompt |
+| `--dry-run` | Preview the patch without applying it |
+
+## Cascade behavior
+
+- `enable api-keys --for orgs` also sets `organization_settings.enabled = true`.
+ Organization API Keys require organizations enabled, so this saves a separate
+ command. The cascade is idempotent.
+- `disable api-keys --for orgs` disables only organization API Keys and leaves
+ organizations enabled.
+- `disable api-keys` without `--for` disables API Keys entirely.
+
+## Clerk API endpoints
+
+| Method | Endpoint | Description |
+| ------ | ----------------------------------------------------------------- | ----------------------------------------------------------------------- |
+| GET | `/v1/platform/applications/{appId}/instances/{instanceId}/config` | Fetch current config for diff before mutation |
+| PATCH | `/v1/platform/applications/{appId}/instances/{instanceId}/config` | Patch `api_keys_settings.*` (with `?dry_run=true` when `--dry-run` set) |

packages/cli-core/src/commands/api-keys/index.test.ts

@@ -0,0 +1,230 @@
+import { test, expect, describe, beforeEach, afterEach, spyOn, mock } from "bun:test";
+import { mkdtemp, rm } from "node:fs/promises";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { _setConfigDir, setProfile } from "../../lib/config.ts";
+import {
+ captureLog,
+ credentialStoreStubs,
+ gitStubs,
+ promptsStubs,
+ stubFetch,
+} from "../../test/lib/stubs.ts";
+
+mock.module("../../lib/credential-store.ts", () => credentialStoreStubs);
+mock.module("../../lib/git.ts", () => gitStubs);
+mock.module("@inquirer/prompts", () => promptsStubs);
+mock.module("../../lib/spinner.ts", () => ({
+ withSpinner: async (_msg: string, fn: () => Promise<unknown>) => fn(),
+}));
+
+describe("clerk enable/disable api-keys", () => {
+ const originalEnv = { ...process.env };
+ const originalFetch = globalThis.fetch;
+ let tempDir: string;
+ let logSpy: ReturnType<typeof spyOn>;
+ let errorSpy: ReturnType<typeof spyOn>;
+ let captured: ReturnType<typeof captureLog>;
+
+ beforeEach(async () => {
+ tempDir = await mkdtemp(join(tmpdir(), "clerk-api-keys-test-"));
+ _setConfigDir(tempDir);
+ process.env.CLERK_PLATFORM_API_KEY = "test_key";
+ process.env.CLERK_PLATFORM_API_URL = "https://test-api.clerk.com";
+
+ logSpy = spyOn(console, "log").mockImplementation(() => {});
+ errorSpy = spyOn(console, "error").mockImplementation(() => {});
+ captured = captureLog();
+
+ stubFetch(async () => {
+ return new Response(JSON.stringify({}), { status: 200 });
+ });
+ });
+
+ afterEach(async () => {
+ captured.teardown();
+ _setConfigDir(undefined);
+ process.env = { ...originalEnv };
+ globalThis.fetch = originalFetch;
+ logSpy.mockRestore();
+ errorSpy.mockRestore();
+ await rm(tempDir, { recursive: true, force: true });
+ });
+
+ async function setupProfile() {
+ await setProfile(process.cwd(), {
+ workspaceId: "org_1",
+ appId: "app_1",
+ instances: { development: "ins_dev" },
+ });
+ }
+
+ test("enable defaults to user API Keys", async () => {
+ let capturedBody = "";
+ stubFetch(async (_input, init) => {
+ if (init?.method === "PATCH") capturedBody = init.body as string;
+ return new Response(JSON.stringify({}), { status: 200 });
+ });
+
+ await setupProfile();
+ const { apiKeysEnable } = await import("./index.ts");
+ await captured.run(() => apiKeysEnable({}));
+
+ const parsed = JSON.parse(capturedBody);
+ expect(parsed.api_keys_settings.enabled).toBe(true);
+ expect(parsed.api_keys_settings.user_api_keys_enabled).toBe(true);
+ expect(parsed.api_keys_settings.orgs_api_keys_enabled).toBeUndefined();
+ expect(parsed.organization_settings).toBeUndefined();
+ });
+
+ test("enable --for orgs enables org API Keys and cascades organizations", async () => {
+ let capturedBody = "";
+ stubFetch(async (_input, init) => {
+ if (init?.method === "PATCH") capturedBody = init.body as string;
+ return new Response(JSON.stringify({}), { status: 200 });
+ });
+
+ await setupProfile();
+ const { apiKeysEnable } = await import("./index.ts");
+ await captured.run(() => apiKeysEnable({ for: ["orgs"] }));
+
+ const parsed = JSON.parse(capturedBody);
+ expect(parsed.api_keys_settings.enabled).toBe(true);
+ expect(parsed.api_keys_settings.orgs_api_keys_enabled).toBe(true);
+ expect(parsed.api_keys_settings.user_api_keys_enabled).toBeUndefined();
+ expect(parsed.organization_settings.enabled).toBe(true);
+ });
+
+ test("enable --for users,orgs sets both API Keys targets", async () => {
+ let capturedBody = "";
+ stubFetch(async (_input, init) => {
+ if (init?.method === "PATCH") capturedBody = init.body as string;
+ return new Response(JSON.stringify({}), { status: 200 });
+ });
+
+ await setupProfile();
+ const { apiKeysEnable } = await import("./index.ts");
+ await captured.run(() => apiKeysEnable({ for: ["users,orgs"] }));
+
+ const parsed = JSON.parse(capturedBody);
+ expect(parsed.api_keys_settings.user_api_keys_enabled).toBe(true);
+ expect(parsed.api_keys_settings.orgs_api_keys_enabled).toBe(true);
+ expect(parsed.organization_settings.enabled).toBe(true);
+ });
+
+ test("enable rejects invalid --for token", async () => {
+ await setupProfile();
+ const { apiKeysEnable } = await import("./index.ts");
+ await expect(captured.run(() => apiKeysEnable({ for: ["machine"] }))).rejects.toThrow(
+ 'Invalid --for value: "machine". Expected "orgs" and/or "users".',
+ );
+ });
+
+ test("enable accepts singular --for aliases", async () => {
+ let capturedBody = "";
+ stubFetch(async (_input, init) => {
+ if (init?.method === "PATCH") capturedBody = init.body as string;
+ return new Response(JSON.stringify({}), { status: 200 });
+ });
+
+ await setupProfile();
+ const { apiKeysEnable } = await import("./index.ts");
+ await captured.run(() => apiKeysEnable({ for: ["user", "org"] }));
+
+ const parsed = JSON.parse(capturedBody);
+ expect(parsed.api_keys_settings.user_api_keys_enabled).toBe(true);
+ expect(parsed.api_keys_settings.orgs_api_keys_enabled).toBe(true);
+ expect(parsed.organization_settings.enabled).toBe(true);
+ });
+
+ test("enable --dry-run plumbs dry_run=true to the API", async () => {
+ let capturedUrl = "";
+ stubFetch(async (input, init) => {
+ if (init?.method === "PATCH") capturedUrl = input.toString();
+ return new Response(JSON.stringify({}), { status: 200 });
+ });
+
+ await setupProfile();
+ const { apiKeysEnable } = await import("./index.ts");
+ await captured.run(() => apiKeysEnable({ dryRun: true }));
+
+ expect(capturedUrl).toContain("dry_run=true");
+ expect(captured.err).toContain("[dry-run]");
+ });
+
+ test("disable with no --for disables API Keys entirely", async () => {
+ let capturedBody = "";
+ stubFetch(async (_input, init) => {
+ if (init?.method === "PATCH") capturedBody = init.body as string;
+ return new Response(
+ JSON.stringify({
+ api_keys_settings: {
+ enabled: true,
+ user_api_keys_enabled: true,
+ orgs_api_keys_enabled: true,
+ },
+ }),
+ { status: 200 },
+ );
+ });
+
+ await setupProfile();
+ const { apiKeysDisable } = await import("./index.ts");
+ await captured.run(() => apiKeysDisable({}));
+
+ const parsed = JSON.parse(capturedBody);
+ expect(parsed.api_keys_settings.enabled).toBe(false);
+ expect(parsed.api_keys_settings.user_api_keys_enabled).toBe(false);
+ expect(parsed.api_keys_settings.orgs_api_keys_enabled).toBe(false);
+ });
+
+ test("disable --for orgs only disables org API Keys", async () => {
+ let capturedBody = "";
+ stubFetch(async (_input, init) => {
+ if (init?.method === "PATCH") capturedBody = init.body as string;
+ return new Response(
+ JSON.stringify({
+ api_keys_settings: {
+ enabled: true,
+ user_api_keys_enabled: true,
+ orgs_api_keys_enabled: true,
+ },
+ }),
+ { status: 200 },
+ );
+ });
+
+ await setupProfile();
+ const { apiKeysDisable } = await import("./index.ts");
+ await captured.run(() => apiKeysDisable({ for: ["orgs"] }));
+
+ const parsed = JSON.parse(capturedBody);
+ expect(parsed.api_keys_settings.enabled).toBeUndefined();
+ expect(parsed.api_keys_settings.user_api_keys_enabled).toBeUndefined();
+ expect(parsed.api_keys_settings.orgs_api_keys_enabled).toBe(false);
+ });
+
+ test("disable shows no changes when already fully disabled", async () => {
+ let patchCalls = 0;
+ stubFetch(async (_input, init) => {
+ if (init?.method === "PATCH") patchCalls++;
+ return new Response(
+ JSON.stringify({
+ api_keys_settings: {
+ enabled: false,
+ user_api_keys_enabled: false,
+ orgs_api_keys_enabled: false,
+ },
+ }),
+ { status: 200 },
+ );
+ });
+
+ await setupProfile();
+ const { apiKeysDisable } = await import("./index.ts");
+ await captured.run(() => apiKeysDisable({}));
+
+ expect(patchCalls).toBe(0);
+ expect(captured.err).toContain("No changes detected");
+ });
+});

.changeset/accept-orgs-users-for-flags.md

@@ -0,0 +1,5 @@
+---
+"clerk": minor
+---
+
+Add `clerk enable api-keys` and `clerk disable api-keys` for toggling API Keys on the linked instance. API Key targeting uses the canonical plural `orgs` and `users` values, while the singular `org` and `user` values continue to work as aliases.

packages/cli-core/src/cli-program.ts

@@ -48,6 +48,7 @@ import { update } from "./commands/update/index.ts";
 import { isClerkSkillInstalled } from "./lib/skill-detection.ts";
 import { orgsEnable, orgsDisable } from "./commands/orgs/index.ts";
 import { billingEnable, billingDisable } from "./commands/billing/index.ts";
+import { apiKeysEnable, apiKeysDisable } from "./commands/api-keys/index.ts";
 import { registerExtras } from "@clerk/cli-extras";
 
 const USER_LIST_ORDER_BY_FIELDS = [
@@ -636,6 +637,10 @@ Give AI agents better Clerk context: install the Clerk skills
  command: "clerk enable billing",
  description: "Enable billing for organizations and users",
  },
+ {
+ command: "clerk enable api-keys",
+ description: "Enable API Keys for users",
+ },
  ]);
 
  enable
@@ -703,6 +708,38 @@ Give AI agents better Clerk context: install the Clerk skills
  ])
  .action(billingEnable);
 
+ enable
+ .command("api-keys")
+ .aliases(["apikeys", "api_keys"])
+ .description("Enable API Keys on the linked instance")
+ .option(
+ "--for <targets...>",
+ "API Keys targets (orgs and/or users), separated by spaces or commas (e.g. orgs users). Defaults to users when omitted.",
+ )
+ .option("--app <id>", "Application ID to target")
+ .option("--instance <id>", "Instance to target (dev, prod, or instance ID)")
+ .option("--yes", "Skip confirmation prompts")
+ .option("--dry-run", "Show the patch that would be sent without applying it")
+ .setExamples([
+ {
+ command: "clerk enable api-keys",
+ description: "Enable API Keys for users",
+ },
+ {
+ command: "clerk enable api-keys --for orgs",
+ description: "Enable API Keys for organizations",
+ },
+ {
+ command: "clerk enable api-keys --for users orgs",
+ description: "Enable API Keys for users and organizations",
+ },
+ {
+ command: "clerk enable api-keys --dry-run",
+ description: "Preview the patch without applying it",
+ },
+ ])
+ .action(apiKeysEnable);
+
  const disable = program
  .command("disable")
  .description("Disable Clerk features on the linked instance")
@@ -716,6 +753,10 @@ Give AI agents better Clerk context: install the Clerk skills
  command: "clerk disable billing",
  description: "Disable billing for organizations and users",
  },
+ {
+ command: "clerk disable api-keys",
+ description: "Disable API Keys",
+ },
  ]);
 
  disable
@@ -764,6 +805,34 @@ Give AI agents better Clerk context: install the Clerk skills
  ])
  .action(billingDisable);
 
+ disable
+ .command("api-keys")
+ .aliases(["apikeys", "api_keys"])
+ .description("Disable API Keys on the linked instance")
+ .option(
+ "--for <targets...>",
+ "API Keys targets (orgs and/or users), separated by spaces or commas (e.g. orgs users). Omit to disable API Keys entirely.",
+ )
+ .option("--app <id>", "Application ID to target")
+ .option("--instance <id>", "Instance to target (dev, prod, or instance ID)")
+ .option("--yes", "Skip confirmation prompts")
+ .option("--dry-run", "Show the patch that would be sent without applying it")
+ .setExamples([
+ {
+ command: "clerk disable api-keys",
+ description: "Disable API Keys entirely",
+ },
+ {
+ command: "clerk disable api-keys --for orgs",
+ description: "Disable API Keys for organizations only",
+ },
+ {
+ command: "clerk disable api-keys --for users",
+ description: "Disable API Keys for users only",
+ },
+ ])
+ .action(apiKeysDisable);
+
  program
  .command("api")
  .description("Make authenticated requests to the Clerk API")

packages/cli-core/src/commands/api-keys/README.md

@@ -0,0 +1,52 @@
+# clerk api-keys (enable/disable)
+
+Toggle Clerk API Keys on the linked instance. The handlers are wired to
+top-level `clerk enable api-keys` and `clerk disable api-keys` commands.
+
+For arbitrary API Keys settings edits, use
+`clerk config patch --json '{"api_keys_settings":{...}}'`.
+
+## Usage
+
+```sh
+clerk enable api-keys [--for <targets>] [options]
+clerk disable api-keys [--for <targets>] [options]
+```
+
+`<targets>` is `orgs` and/or `users`, accepted as space-separated,
+comma-separated, or repeated `--for` flags. The singular aliases `org` and
+`user` are also accepted for backwards compatibility.
+
+```sh
+clerk enable api-keys # defaults to users
+clerk enable api-keys --for orgs users
+clerk enable api-keys --for orgs,users
+clerk disable api-keys # disables API Keys entirely
+clerk disable api-keys --for orgs # disables only organization API Keys
+```
+
+## Options
+
+| Flag | Description |
+| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
+| `--for <targets>` | Targets (`orgs` and/or `users`), separated by spaces or commas. Enable defaults to users; disable without `--for` disables API Keys entirely. |
+| `--app <id>` | Target a specific application |
+| `--instance <id>` | Target a specific instance (dev, prod) |
+| `--yes` | Skip the confirmation prompt |
+| `--dry-run` | Preview the patch without applying it |
+
+## Cascade behavior
+
+- `enable api-keys --for orgs` also sets `organization_settings.enabled = true`.
+ Organization API Keys require organizations enabled, so this saves a separate
+ command. The cascade is idempotent.
+- `disable api-keys --for orgs` disables only organization API Keys and leaves
+ organizations enabled.
+- `disable api-keys` without `--for` disables API Keys entirely.
+
+## Clerk API endpoints
+
+| Method | Endpoint | Description |
+| ------ | ----------------------------------------------------------------- | ----------------------------------------------------------------------- |
+| GET | `/v1/platform/applications/{appId}/instances/{instanceId}/config` | Fetch current config for diff before mutation |
+| PATCH | `/v1/platform/applications/{appId}/instances/{instanceId}/config` | Patch `api_keys_settings.*` (with `?dry_run=true` when `--dry-run` set) |

packages/cli-core/src/commands/api-keys/index.test.ts

@@ -0,0 +1,230 @@
+import { test, expect, describe, beforeEach, afterEach, spyOn, mock } from "bun:test";
+import { mkdtemp, rm } from "node:fs/promises";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { _setConfigDir, setProfile } from "../../lib/config.ts";
+import {
+ captureLog,
+ credentialStoreStubs,
+ gitStubs,
+ promptsStubs,
+ stubFetch,
+} from "../../test/lib/stubs.ts";
+
+mock.module("../../lib/credential-store.ts", () => credentialStoreStubs);
+mock.module("../../lib/git.ts", () => gitStubs);
+mock.module("@inquirer/prompts", () => promptsStubs);
+mock.module("../../lib/spinner.ts", () => ({
+ withSpinner: async (_msg: string, fn: () => Promise<unknown>) => fn(),
+}));
+
+describe("clerk enable/disable api-keys", () => {
+ const originalEnv = { ...process.env };
+ const originalFetch = globalThis.fetch;
+ let tempDir: string;
+ let logSpy: ReturnType<typeof spyOn>;
+ let errorSpy: ReturnType<typeof spyOn>;
+ let captured: ReturnType<typeof captureLog>;
+
+ beforeEach(async () => {
+ tempDir = await mkdtemp(join(tmpdir(), "clerk-api-keys-test-"));
+ _setConfigDir(tempDir);
+ process.env.CLERK_PLATFORM_API_KEY = "test_key";
+ process.env.CLERK_PLATFORM_API_URL = "https://test-api.clerk.com";
+
+ logSpy = spyOn(console, "log").mockImplementation(() => {});
+ errorSpy = spyOn(console, "error").mockImplementation(() => {});
+ captured = captureLog();
+
+ stubFetch(async () => {
+ return new Response(JSON.stringify({}), { status: 200 });
+ });
+ });
+
+ afterEach(async () => {
+ captured.teardown();
+ _setConfigDir(undefined);
+ process.env = { ...originalEnv };
+ globalThis.fetch = originalFetch;
+ logSpy.mockRestore();
+ errorSpy.mockRestore();
+ await rm(tempDir, { recursive: true, force: true });
+ });
+
+ async function setupProfile() {
+ await setProfile(process.cwd(), {
+ workspaceId: "org_1",
+ appId: "app_1",
+ instances: { development: "ins_dev" },
+ });
+ }
+
+ test("enable defaults to user API Keys", async () => {
+ let capturedBody = "";
+ stubFetch(async (_input, init) => {
+ if (init?.method === "PATCH") capturedBody = init.body as string;
+ return new Response(JSON.stringify({}), { status: 200 });
+ });
+
+ await setupProfile();
+ const { apiKeysEnable } = await import("./index.ts");
+ await captured.run(() => apiKeysEnable({}));
+
+ const parsed = JSON.parse(capturedBody);
+ expect(parsed.api_keys_settings.enabled).toBe(true);
+ expect(parsed.api_keys_settings.user_api_keys_enabled).toBe(true);
+ expect(parsed.api_keys_settings.orgs_api_keys_enabled).toBeUndefined();
+ expect(parsed.organization_settings).toBeUndefined();
+ });
+
+ test("enable --for orgs enables org API Keys and cascades organizations", async () => {
+ let capturedBody = "";
+ stubFetch(async (_input, init) => {
+ if (init?.method === "PATCH") capturedBody = init.body as string;
+ return new Response(JSON.stringify({}), { status: 200 });
+ });
+
+ await setupProfile();
+ const { apiKeysEnable } = await import("./index.ts");
+ await captured.run(() => apiKeysEnable({ for: ["orgs"] }));
+
+ const parsed = JSON.parse(capturedBody);
+ expect(parsed.api_keys_settings.enabled).toBe(true);
+ expect(parsed.api_keys_settings.orgs_api_keys_enabled).toBe(true);
+ expect(parsed.api_keys_settings.user_api_keys_enabled).toBeUndefined();
+ expect(parsed.organization_settings.enabled).toBe(true);
+ });
+
+ test("enable --for users,orgs sets both API Keys targets", async () => {
+ let capturedBody = "";
+ stubFetch(async (_input, init) => {
+ if (init?.method === "PATCH") capturedBody = init.body as string;
+ return new Response(JSON.stringify({}), { status: 200 });
+ });
+
+ await setupProfile();
+ const { apiKeysEnable } = await import("./index.ts");
+ await captured.run(() => apiKeysEnable({ for: ["users,orgs"] }));
+
+ const parsed = JSON.parse(capturedBody);
+ expect(parsed.api_keys_settings.user_api_keys_enabled).toBe(true);
+ expect(parsed.api_keys_settings.orgs_api_keys_enabled).toBe(true);
+ expect(parsed.organization_settings.enabled).toBe(true);
+ });
+
+ test("enable rejects invalid --for token", async () => {
+ await setupProfile();
+ const { apiKeysEnable } = await import("./index.ts");
+ await expect(captured.run(() => apiKeysEnable({ for: ["machine"] }))).rejects.toThrow(
+ 'Invalid --for value: "machine". Expected "orgs" and/or "users".',
+ );
+ });
+
+ test("enable accepts singular --for aliases", async () => {
+ let capturedBody = "";
+ stubFetch(async (_input, init) => {
+ if (init?.method === "PATCH") capturedBody = init.body as string;
+ return new Response(JSON.stringify({}), { status: 200 });
+ });
+
+ await setupProfile();
+ const { apiKeysEnable } = await import("./index.ts");
+ await captured.run(() => apiKeysEnable({ for: ["user", "org"] }));
+
+ const parsed = JSON.parse(capturedBody);
+ expect(parsed.api_keys_settings.user_api_keys_enabled).toBe(true);
+ expect(parsed.api_keys_settings.orgs_api_keys_enabled).toBe(true);
+ expect(parsed.organization_settings.enabled).toBe(true);
+ });
+
+ test("enable --dry-run plumbs dry_run=true to the API", async () => {
+ let capturedUrl = "";
+ stubFetch(async (input, init) => {
+ if (init?.method === "PATCH") capturedUrl = input.toString();
+ return new Response(JSON.stringify({}), { status: 200 });
+ });
+
+ await setupProfile();
+ const { apiKeysEnable } = await import("./index.ts");
+ await captured.run(() => apiKeysEnable({ dryRun: true }));
+
+ expect(capturedUrl).toContain("dry_run=true");
+ expect(captured.err).toContain("[dry-run]");
+ });
+
+ test("disable with no --for disables API Keys entirely", async () => {
+ let capturedBody = "";
+ stubFetch(async (_input, init) => {
+ if (init?.method === "PATCH") capturedBody = init.body as string;
+ return new Response(
+ JSON.stringify({
+ api_keys_settings: {
+ enabled: true,
+ user_api_keys_enabled: true,
+ orgs_api_keys_enabled: true,
+ },
+ }),
+ { status: 200 },
+ );
+ });
+
+ await setupProfile();
+ const { apiKeysDisable } = await import("./index.ts");
+ await captured.run(() => apiKeysDisable({}));
+
+ const parsed = JSON.parse(capturedBody);
+ expect(parsed.api_keys_settings.enabled).toBe(false);
+ expect(parsed.api_keys_settings.user_api_keys_enabled).toBe(false);
+ expect(parsed.api_keys_settings.orgs_api_keys_enabled).toBe(false);
+ });
+
+ test("disable --for orgs only disables org API Keys", async () => {
+ let capturedBody = "";
+ stubFetch(async (_input, init) => {
+ if (init?.method === "PATCH") capturedBody = init.body as string;
+ return new Response(
+ JSON.stringify({
+ api_keys_settings: {
+ enabled: true,
+ user_api_keys_enabled: true,
+ orgs_api_keys_enabled: true,
+ },
+ }),
+ { status: 200 },
+ );
+ });
+
+ await setupProfile();
+ const { apiKeysDisable } = await import("./index.ts");
+ await captured.run(() => apiKeysDisable({ for: ["orgs"] }));
+
+ const parsed = JSON.parse(capturedBody);
+ expect(parsed.api_keys_settings.enabled).toBeUndefined();
+ expect(parsed.api_keys_settings.user_api_keys_enabled).toBeUndefined();
+ expect(parsed.api_keys_settings.orgs_api_keys_enabled).toBe(false);
+ });
+
+ test("disable shows no changes when already fully disabled", async () => {
+ let patchCalls = 0;
+ stubFetch(async (_input, init) => {
+ if (init?.method === "PATCH") patchCalls++;
+ return new Response(
+ JSON.stringify({
+ api_keys_settings: {
+ enabled: false,
+ user_api_keys_enabled: false,
+ orgs_api_keys_enabled: false,
+ },
+ }),
+ { status: 200 },
+ );
+ });
+
+ await setupProfile();
+ const { apiKeysDisable } = await import("./index.ts");
+ await captured.run(() => apiKeysDisable({}));
+
+ expect(patchCalls).toBe(0);
+ expect(captured.err).toContain("No changes detected");
+ });
+});

.changeset/accept-orgs-users-for-flags.md

@@ -0,0 +1,5 @@
+---
+"clerk": minor
+---
+
+Add `clerk enable api-keys` and `clerk disable api-keys` for toggling API Keys on the linked instance. API Key targeting uses the canonical plural `orgs` and `users` values, while the singular `org` and `user` values continue to work as aliases.

packages/cli-core/src/cli-program.ts

@@ -48,6 +48,7 @@ import { update } from "./commands/update/index.ts";
 import { isClerkSkillInstalled } from "./lib/skill-detection.ts";
 import { orgsEnable, orgsDisable } from "./commands/orgs/index.ts";
 import { billingEnable, billingDisable } from "./commands/billing/index.ts";
+import { apiKeysEnable, apiKeysDisable } from "./commands/api-keys/index.ts";
 import { registerExtras } from "@clerk/cli-extras";
 
 const USER_LIST_ORDER_BY_FIELDS = [
@@ -636,6 +637,10 @@ Give AI agents better Clerk context: install the Clerk skills
  command: "clerk enable billing",
  description: "Enable billing for organizations and users",
  },
+ {
+ command: "clerk enable api-keys",
+ description: "Enable API Keys for users",
+ },
  ]);
 
  enable
@@ -703,6 +708,38 @@ Give AI agents better Clerk context: install the Clerk skills
  ])
  .action(billingEnable);
 
+ enable
+ .command("api-keys")
+ .aliases(["apikeys", "api_keys"])
+ .description("Enable API Keys on the linked instance")
+ .option(
+ "--for <targets...>",
+ "API Keys targets (orgs and/or users), separated by spaces or commas (e.g. orgs users). Defaults to users when omitted.",
+ )
+ .option("--app <id>", "Application ID to target")
+ .option("--instance <id>", "Instance to target (dev, prod, or instance ID)")
+ .option("--yes", "Skip confirmation prompts")
+ .option("--dry-run", "Show the patch that would be sent without applying it")
+ .setExamples([
+ {
+ command: "clerk enable api-keys",
+ description: "Enable API Keys for users",
+ },
+ {
+ command: "clerk enable api-keys --for orgs",
+ description: "Enable API Keys for organizations",
+ },
+ {
+ command: "clerk enable api-keys --for users orgs",
+ description: "Enable API Keys for users and organizations",
+ },
+ {
+ command: "clerk enable api-keys --dry-run",
+ description: "Preview the patch without applying it",
+ },
+ ])
+ .action(apiKeysEnable);
+
  const disable = program
  .command("disable")
  .description("Disable Clerk features on the linked instance")
@@ -716,6 +753,10 @@ Give AI agents better Clerk context: install the Clerk skills
  command: "clerk disable billing",
  description: "Disable billing for organizations and users",
  },
+ {
+ command: "clerk disable api-keys",
+ description: "Disable API Keys",
+ },
  ]);
 
  disable
@@ -764,6 +805,34 @@ Give AI agents better Clerk context: install the Clerk skills
  ])
  .action(billingDisable);
 
+ disable
+ .command("api-keys")
+ .aliases(["apikeys", "api_keys"])
+ .description("Disable API Keys on the linked instance")
+ .option(
+ "--for <targets...>",
+ "API Keys targets (orgs and/or users), separated by spaces or commas (e.g. orgs users). Omit to disable API Keys entirely.",
+ )
+ .option("--app <id>", "Application ID to target")
+ .option("--instance <id>", "Instance to target (dev, prod, or instance ID)")
+ .option("--yes", "Skip confirmation prompts")
+ .option("--dry-run", "Show the patch that would be sent without applying it")
+ .setExamples([
+ {
+ command: "clerk disable api-keys",
+ description: "Disable API Keys entirely",
+ },
+ {
+ command: "clerk disable api-keys --for orgs",
+ description: "Disable API Keys for organizations only",
+ },
+ {
+ command: "clerk disable api-keys --for users",
+ description: "Disable API Keys for users only",
+ },
+ ])
+ .action(apiKeysDisable);
+
  program
  .command("api")
  .description("Make authenticated requests to the Clerk API")

packages/cli-core/src/commands/api-keys/README.md

@@ -0,0 +1,52 @@
+# clerk api-keys (enable/disable)
+
+Toggle Clerk API Keys on the linked instance. The handlers are wired to
+top-level `clerk enable api-keys` and `clerk disable api-keys` commands.
+
+For arbitrary API Keys settings edits, use
+`clerk config patch --json '{"api_keys_settings":{...}}'`.
+
+## Usage
+
+```sh
+clerk enable api-keys [--for <targets>] [options]
+clerk disable api-keys [--for <targets>] [options]
+```
+
+`<targets>` is `orgs` and/or `users`, accepted as space-separated,
+comma-separated, or repeated `--for` flags. The singular aliases `org` and
+`user` are also accepted for backwards compatibility.
+
+```sh
+clerk enable api-keys # defaults to users
+clerk enable api-keys --for orgs users
+clerk enable api-keys --for orgs,users
+clerk disable api-keys # disables API Keys entirely
+clerk disable api-keys --for orgs # disables only organization API Keys
+```
+
+## Options
+
+| Flag | Description |
+| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
+| `--for <targets>` | Targets (`orgs` and/or `users`), separated by spaces or commas. Enable defaults to users; disable without `--for` disables API Keys entirely. |
+| `--app <id>` | Target a specific application |
+| `--instance <id>` | Target a specific instance (dev, prod) |
+| `--yes` | Skip the confirmation prompt |
+| `--dry-run` | Preview the patch without applying it |
+
+## Cascade behavior
+
+- `enable api-keys --for orgs` also sets `organization_settings.enabled = true`.
+ Organization API Keys require organizations enabled, so this saves a separate
+ command. The cascade is idempotent.
+- `disable api-keys --for orgs` disables only organization API Keys and leaves
+ organizations enabled.
+- `disable api-keys` without `--for` disables API Keys entirely.
+
+## Clerk API endpoints
+
+| Method | Endpoint | Description |
+| ------ | ----------------------------------------------------------------- | ----------------------------------------------------------------------- |
+| GET | `/v1/platform/applications/{appId}/instances/{instanceId}/config` | Fetch current config for diff before mutation |
+| PATCH | `/v1/platform/applications/{appId}/instances/{instanceId}/config` | Patch `api_keys_settings.*` (with `?dry_run=true` when `--dry-run` set) |

packages/cli-core/src/commands/api-keys/index.test.ts

@@ -0,0 +1,230 @@
+import { test, expect, describe, beforeEach, afterEach, spyOn, mock } from "bun:test";
+import { mkdtemp, rm } from "node:fs/promises";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { _setConfigDir, setProfile } from "../../lib/config.ts";
+import {
+ captureLog,
+ credentialStoreStubs,
+ gitStubs,
+ promptsStubs,
+ stubFetch,
+} from "../../test/lib/stubs.ts";
+
+mock.module("../../lib/credential-store.ts", () => credentialStoreStubs);
+mock.module("../../lib/git.ts", () => gitStubs);
+mock.module("@inquirer/prompts", () => promptsStubs);
+mock.module("../../lib/spinner.ts", () => ({
+ withSpinner: async (_msg: string, fn: () => Promise<unknown>) => fn(),
+}));
+
+describe("clerk enable/disable api-keys", () => {
+ const originalEnv = { ...process.env };
+ const originalFetch = globalThis.fetch;
+ let tempDir: string;
+ let logSpy: ReturnType<typeof spyOn>;
+ let errorSpy: ReturnType<typeof spyOn>;
+ let captured: ReturnType<typeof captureLog>;
+
+ beforeEach(async () => {
+ tempDir = await mkdtemp(join(tmpdir(), "clerk-api-keys-test-"));
+ _setConfigDir(tempDir);
+ process.env.CLERK_PLATFORM_API_KEY = "test_key";
+ process.env.CLERK_PLATFORM_API_URL = "https://test-api.clerk.com";
+
+ logSpy = spyOn(console, "log").mockImplementation(() => {});
+ errorSpy = spyOn(console, "error").mockImplementation(() => {});
+ captured = captureLog();
+
+ stubFetch(async () => {
+ return new Response(JSON.stringify({}), { status: 200 });
+ });
+ });
+
+ afterEach(async () => {
+ captured.teardown();
+ _setConfigDir(undefined);
+ process.env = { ...originalEnv };
+ globalThis.fetch = originalFetch;
+ logSpy.mockRestore();
+ errorSpy.mockRestore();
+ await rm(tempDir, { recursive: true, force: true });
+ });
+
+ async function setupProfile() {
+ await setProfile(process.cwd(), {
+ workspaceId: "org_1",
+ appId: "app_1",
+ instances: { development: "ins_dev" },
+ });
+ }
+
+ test("enable defaults to user API Keys", async () => {
+ let capturedBody = "";
+ stubFetch(async (_input, init) => {
+ if (init?.method === "PATCH") capturedBody = init.body as string;
+ return new Response(JSON.stringify({}), { status: 200 });
+ });
+
+ await setupProfile();
+ const { apiKeysEnable } = await import("./index.ts");
+ await captured.run(() => apiKeysEnable({}));
+
+ const parsed = JSON.parse(capturedBody);
+ expect(parsed.api_keys_settings.enabled).toBe(true);
+ expect(parsed.api_keys_settings.user_api_keys_enabled).toBe(true);
+ expect(parsed.api_keys_settings.orgs_api_keys_enabled).toBeUndefined();
+ expect(parsed.organization_settings).toBeUndefined();
+ });
+
+ test("enable --for orgs enables org API Keys and cascades organizations", async () => {
+ let capturedBody = "";
+ stubFetch(async (_input, init) => {
+ if (init?.method === "PATCH") capturedBody = init.body as string;
+ return new Response(JSON.stringify({}), { status: 200 });
+ });
+
+ await setupProfile();
+ const { apiKeysEnable } = await import("./index.ts");
+ await captured.run(() => apiKeysEnable({ for: ["orgs"] }));
+
+ const parsed = JSON.parse(capturedBody);
+ expect(parsed.api_keys_settings.enabled).toBe(true);
+ expect(parsed.api_keys_settings.orgs_api_keys_enabled).toBe(true);
+ expect(parsed.api_keys_settings.user_api_keys_enabled).toBeUndefined();
+ expect(parsed.organization_settings.enabled).toBe(true);
+ });
+
+ test("enable --for users,orgs sets both API Keys targets", async () => {
+ let capturedBody = "";
+ stubFetch(async (_input, init) => {
+ if (init?.method === "PATCH") capturedBody = init.body as string;
+ return new Response(JSON.stringify({}), { status: 200 });
+ });
+
+ await setupProfile();
+ const { apiKeysEnable } = await import("./index.ts");
+ await captured.run(() => apiKeysEnable({ for: ["users,orgs"] }));
+
+ const parsed = JSON.parse(capturedBody);
+ expect(parsed.api_keys_settings.user_api_keys_enabled).toBe(true);
+ expect(parsed.api_keys_settings.orgs_api_keys_enabled).toBe(true);
+ expect(parsed.organization_settings.enabled).toBe(true);
+ });
+
+ test("enable rejects invalid --for token", async () => {
+ await setupProfile();
+ const { apiKeysEnable } = await import("./index.ts");
+ await expect(captured.run(() => apiKeysEnable({ for: ["machine"] }))).rejects.toThrow(
+ 'Invalid --for value: "machine". Expected "orgs" and/or "users".',
+ );
+ });
+
+ test("enable accepts singular --for aliases", async () => {
+ let capturedBody = "";
+ stubFetch(async (_input, init) => {
+ if (init?.method === "PATCH") capturedBody = init.body as string;
+ return new Response(JSON.stringify({}), { status: 200 });
+ });
+
+ await setupProfile();
+ const { apiKeysEnable } = await import("./index.ts");
+ await captured.run(() => apiKeysEnable({ for: ["user", "org"] }));
+
+ const parsed = JSON.parse(capturedBody);
+ expect(parsed.api_keys_settings.user_api_keys_enabled).toBe(true);
+ expect(parsed.api_keys_settings.orgs_api_keys_enabled).toBe(true);
+ expect(parsed.organization_settings.enabled).toBe(true);
+ });
+
+ test("enable --dry-run plumbs dry_run=true to the API", async () => {
+ let capturedUrl = "";
+ stubFetch(async (input, init) => {
+ if (init?.method === "PATCH") capturedUrl = input.toString();
+ return new Response(JSON.stringify({}), { status: 200 });
+ });
+
+ await setupProfile();
+ const { apiKeysEnable } = await import("./index.ts");
+ await captured.run(() => apiKeysEnable({ dryRun: true }));
+
+ expect(capturedUrl).toContain("dry_run=true");
+ expect(captured.err).toContain("[dry-run]");
+ });
+
+ test("disable with no --for disables API Keys entirely", async () => {
+ let capturedBody = "";
+ stubFetch(async (_input, init) => {
+ if (init?.method === "PATCH") capturedBody = init.body as string;
+ return new Response(
+ JSON.stringify({
+ api_keys_settings: {
+ enabled: true,
+ user_api_keys_enabled: true,
+ orgs_api_keys_enabled: true,
+ },
+ }),
+ { status: 200 },
+ );
+ });
+
+ await setupProfile();
+ const { apiKeysDisable } = await import("./index.ts");
+ await captured.run(() => apiKeysDisable({}));
+
+ const parsed = JSON.parse(capturedBody);
+ expect(parsed.api_keys_settings.enabled).toBe(false);
+ expect(parsed.api_keys_settings.user_api_keys_enabled).toBe(false);
+ expect(parsed.api_keys_settings.orgs_api_keys_enabled).toBe(false);
+ });
+
+ test("disable --for orgs only disables org API Keys", async () => {
+ let capturedBody = "";
+ stubFetch(async (_input, init) => {
+ if (init?.method === "PATCH") capturedBody = init.body as string;
+ return new Response(
+ JSON.stringify({
+ api_keys_settings: {
+ enabled: true,
+ user_api_keys_enabled: true,
+ orgs_api_keys_enabled: true,
+ },
+ }),
+ { status: 200 },
+ );
+ });
+
+ await setupProfile();
+ const { apiKeysDisable } = await import("./index.ts");
+ await captured.run(() => apiKeysDisable({ for: ["orgs"] }));
+
+ const parsed = JSON.parse(capturedBody);
+ expect(parsed.api_keys_settings.enabled).toBeUndefined();
+ expect(parsed.api_keys_settings.user_api_keys_enabled).toBeUndefined();
+ expect(parsed.api_keys_settings.orgs_api_keys_enabled).toBe(false);
+ });
+
+ test("disable shows no changes when already fully disabled", async () => {
+ let patchCalls = 0;
+ stubFetch(async (_input, init) => {
+ if (init?.method === "PATCH") patchCalls++;
+ return new Response(
+ JSON.stringify({
+ api_keys_settings: {
+ enabled: false,
+ user_api_keys_enabled: false,
+ orgs_api_keys_enabled: false,
+ },
+ }),
+ { status: 200 },
+ );
+ });
+
+ await setupProfile();
+ const { apiKeysDisable } = await import("./index.ts");
+ await captured.run(() => apiKeysDisable({}));
+
+ expect(patchCalls).toBe(0);
+ expect(captured.err).toContain("No changes detected");
+ });
+});