feat!: migrate resource commands to the dashboard account plane

[nicknisi]

Summary

Resource commands now run on the dashboard account plane using the device-flow OAuth login (workos auth login), instead of environment-scoped API keys. One login covers the whole CLI; per-environment key management is no longer required for day-to-day resource work.

Migrated (13):organization, user, role, permission, membership, invitation, session, event, feature-flag, org-domain, portal, webhook, config

Still API-key/REST (by design):connection, directory, api-key, audit-log, vault, and workos api (the deliberate raw-REST escape hatch). directory was planned to migrate but stayed REST: the account plane has no environment-wide directory listing, and migrating would have forced a new --org requirement onto directory list.

Breaking changes (feat!)

• Auth: migrated commands require workos auth login; WORKOS_API_KEY no longer applies to them (it still works for the commands listed above). Not logged in → exit 4 with a structured auth_required error naming the escape hatches.
• Output shapes: migrated commands emit new curated JSON shapes (consistent with team/project), not the public-API REST shapes.
• Environment targeting: requests target the CLI's active environment (stored env ID, --environment-id to override). A stale or unrecognized environment now errors (environment_unresolved) instead of silently targeting production — this also fixes a latent defect where every dashboard-plane request silently hit the team's production environment.
• Token refresh: an expired access token with a valid refresh token now refreshes silently on the command path; only a truly dead session exits 4.
• Per-command flag divergences are documented in the individual commit messages. Notables: webhook create no longer returns the signing secret (dashboard-only); portal generate-link drops --return-url/--success-url and the audit_logs intent; event list requires --events.

Validation

• 2400+ unit tests, typecheck, build all green.
• No migrated command file touches the API-key plane (grep gate in CI spec); no user-visible surface leaks internal API details (no-graphql-leak.spec.ts extended to the new surface).
• Live smoke against production (sandbox environment): scripts/smoke-dashboard-plane.sh — read tier 17/17, --mutate 44/44 (full CRUD round-trips in a disposable org: organization, org-domain, role+permission, membership incl. deactivate/reactivate, invitation, webhook, portal link), --config-writes 23/23 (snapshot-and-restore on redirect URIs and CORS origins). Includes a negative test proving a bogus --environment-id is refused rather than falling back to production.

Before merge

• Confirm the dashboard capability flag is enabled for all production teams (headless-dashboard/MCP team) — an unflagged team would see 403s on all 13 migrated commands.

Follow-ups (not in this PR)

• M2M/client-credentials auth to restore a first-class headless story for migrated commands.
• Error passthrough: server-side validation messages are currently masked to a generic "could not complete this request" (e.g. org-scoped role slugs must be prefixed org-, which users can't see). A pattern-filtered passthrough would keep errors actionable without leaking internals.
• Migrate connection/api-key/audit-log/directory once the missing account-plane operations exist.
• Grammar consistency: authkit redirect-uris list vs authkit cors get for equivalent reads.

[devin-ai-integration]

✅ Devin Review: No Issues Found

Devin Review analyzed this PR and found no bugs or issues to report.

[greptile-apps]

Greptile Summary

This PR migrates 13 resource commands (organization, user, role, permission, membership, invitation, session, event, feature-flag, org-domain, portal, webhook, config) from the API-key REST plane to the WorkOS dashboard account plane, using the device-flow OAuth session established by workos auth login. Per-environment API-key management is no longer required for day-to-day resource work on these commands.

• New auth layer: requireCommandToken() in command-auth.ts provides a structured exit-4 path for unauthenticated dashboard commands; silent token refresh is extracted into the shared refreshIfExpired() used by both this guard and the existing ensureAuthenticated() install flow.
• Environment targeting: resolveEnvironmentTarget() enforces a strict invariant — environment-scoped mutations are pre-validated against the team's live environment list; a stale stored ID exits with environment_stale rather than silently targeting production. Reads use the stored ID directly (accepted trade-off documented in code).
• Catalog-backed operations: Commands now look up operation documents from a vendored snapshot (mcp-catalog.snapshot.json) rather than hand-writing GraphQL, and a no-graphql-leak.spec.ts gate enforces that no internal field names surface in user-visible strings.

Confidence Score: 5/5

• This PR is safe to merge once the capability flag is confirmed enabled for all production teams (noted in the PR checklist).
• The migration is carefully layered: auth, environment targeting, catalog operations, and error translation each have clear ownership and test coverage. The mutation pre-validation invariant (no silent production fallback on stale IDs) is well-enforced and exercised by the negative smoke test. The one speculative concern — whether server validation messages from typed error variants could expose internal terminology — is isolated to error paths and depends entirely on the server's own message content, which the server team controls.
• The passthrough of result.message from UserlandApplicationValidationFailed in config.ts and URI-validation error messages in authkit.ts are worth a quick check of the server's actual message content; the no-graphql-leak.spec.ts does not currently scan those paths.

Important Files Changed

Filename	Overview
src/lib/command-auth.ts	New auth guard for dashboard-plane commands. refreshIfExpired correctly handles all token states (valid, expired+refresh, invalid_grant, network error); requireCommandToken translates no-session cases into structured exit-4 errors. The WORKOS_API_KEY variant copy is well-differentiated. No sensitive fields are logged. Well-tested in command-auth.spec.ts.
src/lib/dashboard-graphql.ts	Minimal GraphQL client for the account plane. Timeout, abort, and error classification (forbidden/http/graphql/network) are all handled. The multipart upload path correctly follows the GraphQL multipart spec with the CSRF header. assertNullPlaceholder prevents silent variable path mismatches that would clear branding assets.
src/lib/environment-target.ts	Solid environment resolution with correct mutation pre-validation vs. read fast-path, opportunistic profile healing via clientId join, and distinct forbidden vs. network-error copy. The 403 from fetchTeamEnvironments now correctly surfaces the forbidden message rather than a transient retry hint.
src/lib/dashboard-operation.ts	Clean composition layer: auth → catalog lookup → environment targeting → wire request → structured error exit. reportDashboardError is typed as never, so TypeScript correctly verifies the Promise<T> return type without a post-catch return statement.
src/commands/config.ts	Migrated from REST to dashboard plane. The read-merge-write pattern for redirect and CORS adds is documented with its accepted race window. The scan-cap guard on redirect URIs correctly uses listMetadata.after to refuse a truncated read. The UserlandApplicationValidationFailed.message is passed through to users without the graphql-leak spec covering that path.
src/commands/authkit.ts	New command surface for per-environment AuthKit config. Wildcard-origin guard (rejectWildcardOrigins) is correctly placed before requireCommandToken. Discriminated union error variant messages (result.message) for redirect/logout URI errors are passed through to users without graphql-leak spec coverage.
src/commands/feature-flag.ts	Migrated to dashboard plane with project-scoped operations. The resolveProjectId extra round-trip is necessary and catches stale environment IDs implicitly. The read-merge-write for enable/disable/targeting is correct. Target ID prefix validation (user_/org_) is enforced client-side.
src/commands/organization.ts	Migration adds domain state validation (verified/pending), enforces the all-same-state constraint via domainsDeveloperVerified, and adds the confirmation gate on delete. The curated output shape is clearly defined and tested.
src/catalog/no-graphql-leak.spec.ts	Good coverage of static command metadata and CLI-owned error constants. Gap: does not exercise server-supplied message fields from typed discriminated union error variants (e.g., UserlandApplicationValidationFailed.message in config.ts, URI error messages in authkit.ts), which are passed through to users outside the spec's scan.
src/lib/settings.ts	getCliAuthClientId is now config-only (no env override) with a clear comment explaining the WORKOS_CLIENT_ID collision hazard. getAuthkitDomain keeps its env override via WORKOS_AUTHKIT_DOMAIN which is correctly scoped.
src/commands/webhook.ts	Migrated to dashboard plane. The signing-secret removal is explicitly documented in comments and the file-level docstring. Destructive delete is correctly gated by confirmDestructive.
src/lib/api-key.ts	New getApiBaseUrlSource returns provenance alongside the URL (useful for the "→ non-prod" indicator). normalizeApiBaseUrl validates protocol and strips trailing slashes, failing loudly instead of surfacing as an opaque TypeError.
scripts/smoke-dashboard-plane.sh	Comprehensive smoke test covering read (17/17), mutate (44/44), and config-writes (23/23) tiers, including a negative test proving bogus --environment-id is rejected. No TLS bypass or hardcoded secrets found.

Sequence Diagram

sequenceDiagram
participant CLI as CLI Command
participant CA as requireCommandToken()
participant TR as token-refresh-client
participant ET as resolveEnvironmentTarget()
participant DG as dashboardGraphqlRequest()
participant Server as WorkOS Dashboard /graphql
CLI->>CA: requireCommandToken()
alt token still valid
CA-->>CLI: accessToken
else token expired, refresh token present
CA->>TR: refreshAccessToken(domain, clientId)
TR->>Server: POST /oauth2/token (refresh_token grant)
Server-->>TR: new access_token + refresh_token
TR-->>CA: "RefreshResult{success, accessToken}"
CA->>CA: updateTokens()
CA-->>CLI: accessToken
else no session / invalid_grant
CA->>CLI: exitWithAuthRequired(exit 4)
end
CLI->>ET: "resolveEnvironmentTarget(token, {forMutation})"
alt "forMutation=false, stored envId exists"
ET-->>CLI: "{environmentId, source:'profile'} (fast path, no network)"
else "forMutation=true OR no stored envId"
ET->>Server: teamProjectsV2 (team-scoped, no env header)
Server-->>ET: projects + environments list
ET->>ET: healActiveProfile() via clientId join
alt envId not found in team list
ET->>CLI: exitWithError(environment_stale)
else envId valid
ET-->>CLI: "{environmentId, source}"
end
end
CLI->>DG: "dashboardGraphqlRequest(document, {token, environmentId, variables})"
DG->>Server: POST /graphql (Bearer token, x-url-environment-id header)
alt success
Server-->>DG: "{data: T}"
DG-->>CLI: T
else 401/403
Server-->>DG: HTTP 401/403
DG->>CLI: reportDashboardError → exitWithError(forbidden)
else graphql errors
Server-->>DG: "{errors:[...]}"
DG->>CLI: reportDashboardError → exitWithError(graphql_error)
end

Loading

_{Reviews (8): Last reviewed commit: "docs: document the authkit and branding ..." | Re-trigger Greptile}

[greptile-apps]

HTTP 401 misclassified as "capability not enabled"

Both 401 and 403 are mapped to 'forbidden', which surfaces the message "This account-plane capability is not enabled for this team, or the logged-in account is not backed by a WorkOS dashboard team." A 401 from the server means the bearer token was rejected as invalid — the most common real-world trigger being remote session invalidation (admin deactivation, password change, explicit logout from another device). In that case requireCommandToken() sees a locally-valid (not expired) token, issues the request, gets back a 401, and the user is told "capability not enabled" with no hint to re-authenticate. Distinguishing status === 401 with a separate error code — something like 'invalid_session' — and routing it through copy like "Session was invalidated. Run workos auth login to re-authenticate" would make this edge case actionable. Does the WorkOS dashboard GraphQL endpoint ever return HTTP 401 (as opposed to 403) for a rejected bearer token? If the server guarantees 403 for all auth failures, this distinction can be dropped.

Prompt To Fix With AI

This is a comment left during a code review.
Path: src/lib/dashboard-graphql.ts
Line: 123-129
Comment:
**HTTP 401 misclassified as "capability not enabled"**
Both 401 and 403 are mapped to `'forbidden'`, which surfaces the message "This account-plane capability is not enabled for this team, or the logged-in account is not backed by a WorkOS dashboard team." A 401 from the server means the bearer token was rejected as invalid — the most common real-world trigger being remote session invalidation (admin deactivation, password change, explicit logout from another device). In that case `requireCommandToken()` sees a locally-valid (not expired) token, issues the request, gets back a 401, and the user is told "capability not enabled" with no hint to re-authenticate. Distinguishing `status === 401` with a separate error code — something like `'invalid_session'` — and routing it through copy like "Session was invalidated. Run `workos auth login` to re-authenticate" would make this edge case actionable. Does the WorkOS dashboard GraphQL endpoint ever return HTTP 401 (as opposed to 403) for a rejected bearer token? If the server guarantees 403 for all auth failures, this distinction can be dropped.
How can I resolve this? If you propose a fix, please make it concise.