[seanperez29]

Problem

A Clerk Dashboard workspace member whose role has no Platform API access gets an unexplained 403 from every CLI command. Support, Viewer and Guest are roles any customer can give a teammate (clerk_go api/dapi/constants/rbac.go). For example:

Failed to fetch application (403): Workspace role has no Platform API access

Two more problems in the same situation:

• clerk auth login suggests clerk apps create, which fails the same way.
• A role that is missing one scope (for example, Developer creating an application) gets Missing authorization scopes, without the scope's name.

The backend already explains both cases:

• No access: platform_oauth_access_token_role_has_no_access, with meta.role and meta.roles_with_access. Defined in api/apierror/platform.go, raised in platformauth/oat_strategy.go.
• Missing scope: authorization_missing_scopes, with meta.scopes. Defined in api/apierror/auth.go.

The CLI printed only the short message.

Change

The global error handler now explains Platform API 403s that carry either of those two codes:

• No Platform API access: names the role and the roles that have access. It says to ask a workspace owner or admin to change the role, or to switch workspaces and run clerk auth logout and clerk auth login. Logging out comes first because, in agent mode, clerk auth login returns early when a session exists.
• Managed workspace: its roles can't be changed, so it points to CLERK_PLATFORM_API_KEY instead.
• Missing scope: names the scope. When CLERK_PLATFORM_API_KEY is set, it says the key lacks the scope, not the role.
• Agent mode and --json: the error keeps the API's code and errors unchanged and adds a docsUrl for managing team access.
• Login warning: clerk auth login's default-application warning uses the same explanation.

Every other 403, Backend API or Frontend API error, and other error code prints as before.

Before:

Failed to fetch application (403): Workspace role has no Platform API access

After:

Failed to fetch application (403): Your role in this Clerk workspace (org:support) has no Platform API access, so the CLI can't read or change its applications.
Ask an owner or admin of the workspace to change your role to one of: org:owner, org:admin, org:developer.
To use another workspace, switch to it in the Clerk Dashboard, then run `clerk auth logout` and `clerk auth login`.

For more information, see: https://clerk.com/docs/guides/dashboard/manage-team-access

Verification

• New tests in errors.test.ts, cli-program.test.ts and first-application.test.ts:
  • human and JSON output;
  • managed workspaces and a missing meta;
  • both missing-scope cases;
  • 403s that should print as before.
• Checks: bun run format, lint, typecheck, test and format:check all pass.
• Manual run: clerk apps list and clerk link --app against a local server returning the real 403 body, in human and agent mode.

Not changed here

• After login, autoclaim treats any 403 as "your account does not have an active organization" (lib/autoclaim.ts).
• isAuthError() treats every 403 as a sign-in problem, so migrate export reports this role error as not being signed in.

Both are worth fixing on their own.

🤖 Generated with Claude Code

[changeset-bot]

🦋 Changeset detected

Latest commit: 279f03b

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
clerk	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[coderabbitai]

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

• Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts