#23009: Onboard: persist env-backed API keys as secret refs
commands
maintainer
size: M
Cluster:
Model Authentication Enhancements
## Summary
- route onboarding API-key persistence through shared credential builders that can emit either plaintext `key` or `keyRef`
- add env-ref detection for API key inputs via:
- explicit `${ENV_VAR}` syntax
- value match against provider-known env vars (for example `OPENAI_API_KEY`)
- when an env-backed value is detected, persist `keyRef: { source: "env", id: "ENV_VAR" }` instead of plaintext in auth profiles
- keep backward compatibility: if no env match/ref is found, onboarding keeps writing plaintext keys exactly as before
## Scope Boundary
- no runtime resolution behavior changes in this PR (activation/failover remains in earlier stack PRs)
- no provider-specific onboarding flow migration in this PR (handled in follow-up PRs)
## Validation
- `pnpm check`
- `pnpm vitest run src/commands/onboard-auth.credentials.test.ts`
<!-- greptile_comment -->
<h3>Greptile Summary</h3>
Routes API key persistence through a unified credential builder that detects environment-backed values and persists them as `keyRef` instead of plaintext. Supports both explicit `${ENV_VAR}` syntax and automatic detection via value matching against provider-specific environment variables. Maintains backward compatibility by falling back to plaintext storage when no environment reference applies.
- refactored 18 provider-specific API key setters to use shared `buildApiKeyCredential` helper
- added `resolveApiKeySecretInput` to detect and convert env-backed values to `SecretRef` objects
- added provider-to-env-var mapping for 17 providers (anthropic, google, moonshot, etc.)
- added comprehensive test coverage for env reference detection, explicit `${ENV}` syntax, plaintext fallback, and metadata preservation
<h3>Confidence Score: 5/5</h3>
- This PR is safe to merge with minimal risk
- Well-structured refactoring with comprehensive test coverage, proper type safety, secure handling of secret references, and maintained backward compatibility. No logical errors or security issues identified.
- No files require special attention
<sub>Last reviewed commit: cc60609</sub>
<!-- greptile_other_comments_section -->
<!-- /greptile_comment -->
Most Similar PRs
#23000: Secrets: add migrate rollback and skill ref support
by joshavant · 2026-02-21
73.4%
#10258: fix(config): preserve ${ENV_VAR} references when writing config (#9...
by nu-gui · 2026-02-06
72.2%
#7813: feat(onboard): validate Venice API keys during setup
by jonisjongithub · 2026-02-03
72.0%
#23015: Onboard: store OpenAI auth in profiles instead of .env
by joshavant · 2026-02-21
71.1%
#23026: Onboard: move volcengine/byteplus auth from .env to profiles
by joshavant · 2026-02-21
70.9%
#23444: Gateway: move auth token storage to state dotenv by default
by bmendonca3 · 2026-02-22
70.6%
#21520: feat(onboard): add Cencori provider.
by bolaabanjo · 2026-02-20
70.5%
#19841: feat: add Amazon Bedrock as first-class onboarding provider
by elbeyf · 2026-02-18
69.6%
#22858: Gateway: add eager secrets runtime snapshot activation
by joshavant · 2026-02-21
69.5%
#21216: feat(models): add apiKeyHelper for dynamic API key resolution
by chrisvanbuskirk · 2026-02-19
69.0%