Auth: support multiple platform environments (per-host credential profiles)

While dogfooding the CLI (1.5.0, agent-driven) against a second Clerk platform environment, we hit a wall on auth: CLERK_PLATFORM_API_URL cleanly redirects requests, but the credential store only holds one OAuth token and clerk auth login has no notion of which host a token belongs to. Logging into the alternate environment would clobber the production login, so the only safe path is minting a platform API key for the second environment and threading CLERK_PLATFORM_API_KEY through every call.

That workaround is fine for CI but makes non-production work second-class for interactive use. A per-host credential store (key tokens by platform API URL) or an explicit --profile on auth login/api/config would make switching environments first-class. Bonus: clerk doctor could report which environment the stored token belongs to.

What if there was an association w/ environment or token per directory?

pushd /a
clerk switch-env staging
clerk login # select workspace a
popd

pushd /b
clerk switch-env prod
clerk login # select workspace b
popd

pushd /c
clerk switch-env prod
clerk login # select workspace c
popd

cd /a
clerk whoami # user on staging env (workspace a)

To me, this seems easy to reason about.

Correction after more digging: the core of this ask already ships in 1.5.0. clerk switch-env lists production and staging profiles (OAuth client ID, OAuth base URL, Platform API URL, and Backend API URL all switch together), and the credential store keys tokens per environment (oauth-access-token:<envName> in the keychain, credentials.<envName> for the file fallback), so logging into staging leaves the production token intact. I filed this issue having missed the command entirely.

Which points at what I think is the real residual issue: discoverability. switch-env doesn't appear in clerk --help (the closest entry is env, which manages environment variables), so the feature is invisible unless you already know its name. Suggestions:

surface switch-env in the top-level help output
have clerk whoami and/or clerk doctor report the active environment alongside the account

Happy for this to be closed in favor of a narrower "make switch-env discoverable" item, or retitled and kept; either works.

We hid it because switch-env is not useful to users outside of Clerk. Perhaps we can display it if we recognize the user has a Clerk email address. That of course requires the user log in at least once. wdyt?

fix(env): surface CLERK_PLATFORM_API_URL credential mismatch

Navigation Menu

Repository navigation

Auth: support multiple platform environments (per-host credential profiles) #329

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Auth: support multiple platform environments (per-host credential profiles) #329

Description

Activity

jfoshee commented on Jun 11, 2026

jacekradko commented on Jun 11, 2026

jfoshee commented on Jun 12, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions