fix(auth): explain managed-workspace claim rejections during login

.changeset/autoclaim-managed-workspace.md

@@ -0,0 +1,5 @@
+---
+"clerk": patch
+---
+
+`clerk auth login` now explains why a keyless application could not be claimed when the active workspace is managed by an integration such as Vercel Marketplace or Stripe. When the Platform API rejects the claim with the error code `accountless_application_managed_workspace`, the CLI prints the API message, for example "Unable to claim - The target application cannot be claimed into the current workspace. Select a different workspace and try again.", instead of the generic "no active organization" warning, and keeps the local claim token so the next `clerk auth login` from a workspace you own claims the application.

packages/cli-core/src/commands/auth/login.test.ts

@@ -1,6 +1,7 @@
 import { test, expect, describe, afterEach, beforeEach, mock, spyOn } from "bun:test";
 import { AuthError } from "../../lib/errors.ts";
 import { useCaptureLog, credentialStoreStubs, configStubs } from "../../test/lib/stubs.ts";
+import type { AutoclaimResult } from "../../lib/autoclaim.ts";
 
 const actualConstants = await import("../../lib/constants.ts");
 const actualEnvironment = await import("../../lib/environment.ts");
@@ -20,6 +21,9 @@ const mockIsHuman = mock();
 const mockConfirm = mock();
 const mockOpenBrowser = mock();
 const mockEnsureFirstApplication = mock<() => Promise<void>>(() => Promise.resolve());
+const mockAttemptAutoclaim = mock<() => Promise<AutoclaimResult>>(() =>
+  Promise.resolve({ status: "not_keyless" }),
+);
 
 mock.module("../../lib/credential-store.ts", () => ({
   ...credentialStoreStubs,
@@ -93,7 +97,7 @@ mock.module("../../lib/first-application.ts", () => ({
 }));
 
 mock.module("../../lib/autoclaim.ts", () => ({
-  attemptAutoclaim: async () => ({ status: "not_keyless" }),
+  attemptAutoclaim: () => mockAttemptAutoclaim(),
 }));
 
 const { setLogLevel } = await import("../../lib/log.ts");
@@ -127,6 +131,8 @@ describe("login", () => {
     mockOpenBrowser.mockReset();
     mockEnsureFirstApplication.mockReset();
     mockEnsureFirstApplication.mockResolvedValue(undefined);
+    mockAttemptAutoclaim.mockReset();
+    mockAttemptAutoclaim.mockResolvedValue({ status: "not_keyless" });
     mockIsHuman.mockReturnValue(false);
     mockOpenBrowser.mockResolvedValue({ ok: true, launcher: "test" });
     mockRevokeToken.mockResolvedValue("revoked");
@@ -588,6 +594,38 @@ describe("login", () => {
     expect(mockEnsureFirstApplication).toHaveBeenCalledTimes(1);
   });
 
+  test("explains a managed-workspace claim rejection with the provider named by the API", async () => {
+    mockGetValidToken.mockResolvedValue("existing-token");
+    mockGetAuth.mockResolvedValue({ userId: "user_123" });
+    mockFetchUserInfo.mockResolvedValue({ userId: "user_123", email: "[email protected]" });
+    mockAttemptAutoclaim.mockResolvedValue({
+      status: "managed_workspace",
+      longMessage:
+        "The target application cannot be claimed into the current workspace. Select a different workspace and try again.",
+    });
+
+    await runLogin();
+
+    expect(captured.err).toContain(
+      "Unable to claim - The target application cannot be claimed into the current workspace. Select a different workspace and try again.",
+    );
+    expect(captured.err).not.toContain("claim the application there");
+    expect(captured.err).not.toContain("does not have an active organization");
+  });
+
+  test("falls back to a generic provider when the managed-workspace rejection has no long message", async () => {
+    mockGetValidToken.mockResolvedValue("existing-token");
+    mockGetAuth.mockResolvedValue({ userId: "user_123" });
+    mockFetchUserInfo.mockResolvedValue({ userId: "user_123", email: "[email protected]" });
+    mockAttemptAutoclaim.mockResolvedValue({ status: "managed_workspace", longMessage: null });
+
+    await runLogin();
+
+    expect(captured.err).toContain(
+      "Unable to claim - this workspace is managed by an integration provider.",
+    );
+  });
+
   test("does not call ensureFirstApplication when existing session is reused", async () => {
     mockGetValidToken.mockResolvedValue("existing-token");
     mockGetAuth.mockResolvedValue({ userId: "user_123" });

packages/cli-core/src/commands/auth/login.ts

@@ -224,6 +224,14 @@ const CLAIM_WARNINGS: Partial<Record<AutoclaimResult["status"], string>> = {
     "Auto-claim failed due to a temporary error. It will be retried on your next `clerk auth login`.",
 };
 
+function claimWarning(result: AutoclaimResult): string | undefined {
+  if (result.status === "managed_workspace") {
+    // The API message already names the provider and says what to do.
+    return `Unable to claim - ${result.longMessage ?? "this workspace is managed by an integration provider."}`;
+  }
+  return CLAIM_WARNINGS[result.status];
+}
+
 async function handleAutoclaim(cwd: string): Promise<AutoclaimResult> {
   const result = await attemptAutoclaim(cwd);
 
@@ -232,7 +240,7 @@ async function handleAutoclaim(cwd: string): Promise<AutoclaimResult> {
     log.success(`Claimed and linked application: \`${label}\``);
   }
 
-  const warning = CLAIM_WARNINGS[result.status];
+  const warning = claimWarning(result);
   if (warning) log.warn(warning);
 
   return result;
@@ -243,6 +251,7 @@ async function loginNextSteps(result: AutoclaimResult): Promise<readonly string[
     return result.envPulled ? NEXT_STEPS.AUTOCLAIMED : NEXT_STEPS.AUTOCLAIMED_NO_ENV;
   }
   if (result.status === "failed") return NEXT_STEPS.AUTOCLAIM_RETRY;
+  if (result.status === "managed_workspace") return NEXT_STEPS.AUTOCLAIM_SWITCH_WORKSPACE;
   if (result.status === "not_found" || result.status === "no_organization") {
     return NEXT_STEPS.AUTOCLAIM_MANUAL_LINK;
   }

packages/cli-core/src/lib/autoclaim.test.ts

@@ -19,6 +19,19 @@ const MOCK_APP = {
   ],
 };
 
+const MANAGED_WORKSPACE_LONG_MESSAGE =
+  "This workspace is managed by Vercel. Switch to a workspace you own and claim the application there.";
+
+const MANAGED_WORKSPACE_BODY = JSON.stringify({
+  errors: [
+    {
+      code: "accountless_application_managed_workspace",
+      message: "Cannot claim into a managed workspace",
+      long_message: MANAGED_WORKSPACE_LONG_MESSAGE,
+    },
+  ],
+});
+
 describe("attemptAutoclaim", () => {
   const originalFetch = globalThis.fetch;
   let tempDir: string;
@@ -124,6 +137,35 @@ describe("attemptAutoclaim", () => {
     expect(clearBreadcrumbSpy).toHaveBeenCalled();
   });
 
+  test("returns no_organization and clears breadcrumb on 403 with an unrelated error code", async () => {
+    withBreadcrumb("forbidden_token");
+    const body = JSON.stringify({
+      errors: [{ code: "authorization_invalid", message: "Request not allowed" }],
+    });
+    stubFetch(async () => new Response(body, { status: 403 }));
+
+    const result = await run();
+
+    expect(result.status).toBe("no_organization");
+    expect(clearBreadcrumbSpy).toHaveBeenCalled();
+  });
+
+  test("returns managed_workspace with the API long_message and preserves breadcrumb on 403 accountless_application_managed_workspace", async () => {
+    withBreadcrumb("managed_token");
+    stubFetch(async () => new Response(MANAGED_WORKSPACE_BODY, { status: 403 }));
+
+    const result = await run();
+
+    expect(result.status).toBe("managed_workspace");
+    if (result.status === "managed_workspace") {
+      expect(result.longMessage).toBe(MANAGED_WORKSPACE_LONG_MESSAGE);
+    }
+    // The claim token must survive: the user switches workspace, then runs
+    // `clerk auth login` again to claim the same application.
+    expect(clearBreadcrumbSpy).not.toHaveBeenCalled();
+    expect(linkAppSpy).not.toHaveBeenCalled();
+  });
+
   test("returns failed (preserves breadcrumb) on 400 — could be recoverable (e.g. 401 re-login)", async () => {
     withBreadcrumb("bad_token");
     stubFetch(async () => new Response("Bad Request", { status: 400 }));

packages/cli-core/src/lib/autoclaim.ts

@@ -7,13 +7,24 @@ import { pull } from "../commands/env/pull.ts";
 import { log } from "./log.ts";
 
 type Claimed = { status: "claimed"; app: Application; envPulled: boolean };
+/** The claim can never succeed with this token; the breadcrumb is cleared. */
 type Terminal = { status: "not_found" | "no_organization" };
+/**
+ * The token's workspace is provisioned by an integration (Vercel Marketplace,
+ * Stripe), so nothing can be claimed into it. The breadcrumb is kept: the user
+ * switches to a workspace they own and the next `clerk auth login` retries.
+ * `longMessage` is the API's `long_message`, which names the provider.
+ */
+type ManagedWorkspace = { status: "managed_workspace"; longMessage: string | null };
 type Failed = { status: "failed"; error: Error };
 type Skipped = { status: "not_keyless" };
 
-export type AutoclaimResult = Claimed | Terminal | Failed | Skipped;
+export type AutoclaimResult = Claimed | Terminal | ManagedWorkspace | Failed | Skipped;
 
-type ClaimAttempt = { status: "claimed"; app: Application } | Terminal | Failed;
+type ClaimAttempt = { status: "claimed"; app: Application } | Terminal | ManagedWorkspace | Failed;
+
+/** PLAPI error code for a claim into a provider-managed workspace. */
+const MANAGED_WORKSPACE_CODE = "accountless_application_managed_workspace";
 
 const TERMINAL_BY_STATUS: Record<number, Terminal["status"]> = {
   404: "not_found",
@@ -28,7 +39,7 @@ export async function attemptAutoclaim(cwd: string): Promise<AutoclaimResult> {
   const appName = await deriveProjectName(cwd);
   const result = await tryClaim(breadcrumb.claimToken, appName);
 
-  if (result.status === "failed") return result;
+  if (result.status === "failed" || result.status === "managed_workspace") return result;
 
   await clearKeylessBreadcrumb(cwd);
 
@@ -75,7 +86,16 @@ async function tryPullEnv(): Promise<boolean> {
   }
 }
 
-function classifyClaimError(error: unknown): Terminal | Failed {
+function classifyClaimError(error: unknown): Terminal | ManagedWorkspace | Failed {
+  if (
+    error instanceof PlapiError &&
+    error.status === 403 &&
+    error.code === MANAGED_WORKSPACE_CODE
+  ) {
+    log.debug(`Claim returned 403 ${MANAGED_WORKSPACE_CODE}: classified as managed_workspace`);
+    return { status: "managed_workspace", longMessage: error.longMessage };
+  }
+
   if (error instanceof PlapiError && error.status in TERMINAL_BY_STATUS) {
     const status = TERMINAL_BY_STATUS[error.status]!;
     log.debug(`Claim returned ${error.status}: classified as ${status}`);

packages/cli-core/src/lib/next-steps.ts

@@ -33,6 +33,10 @@ export const NEXT_STEPS = {
     "Run `clerk auth login` again to retry auto-claim",
     "Run `clerk link` to connect your application manually",
   ],
+  AUTOCLAIM_SWITCH_WORKSPACE: [
+    "Select a different workspace in the Clerk Dashboard",
+    "Run `clerk auth login` again to proceed",
+  ],
   ENABLE_ORGS: [
     "Run `clerk config schema --keys organization_settings` to see all available settings",
     "Run `clerk config pull --keys organization_settings` to see current values",