Skip to main content

​
Migration Guide

This guide covers migrating from deprecated patterns to the new zero-plaintext credential architecture.

​
1. Migrate from IDW_PASSPHRASE to Keychain / Session Tokens

​
Local Development — Use Keychain

The IDW_PASSPHRASE environment variable is deprecated. Replace it with OS keychain storage: 
# Remove the env var from your shell profile
# Then store the passphrase in the keychain:
idw auth login
The passphrase is now resolved automatically on every idw command. Remove any IDW_PASSPHRASE references from .bashrc, .zshrc, .env, or similar files.

​
CI / Headless — Use Session Tokens

For CI pipelines, replace IDW_PASSPHRASE with a session token: 
# On your local machine, create a token:
idw auth token create --label "github-actions" --expires 7d

# In your CI environment, set:
export IDW_SESSION_TOKEN="idwst_..."
The token wraps the passphrase with PBKDF2 + AES-256-GCM. Unlike the raw passphrase, tokens are scoped (labeled), time-limited, and individually revocable.
IDW_PASSPHRASE still works but emits a deprecation warning on every use. It will be removed in a future major version.

​
2. Migrate Provider Admin Keys to Vault Passports

Provider admin credentials (AWS keys, OpenAI admin keys, etc.) should no longer live in plaintext environment variables. Store them as encrypted privilege passports in the vault.

​
Option A: Interactive Bootstrap

The fastest path — the wizard prompts for each provider’s admin credentials: 
idw auth bootstrap
This creates passports with:
  • Visa type: privilege
  • Tags: admin, admin:<provider>, provisioning

​
Option B: Manual Import

Import admin keys individually: 
echo "sk-admin-..." | idw create --name "OpenAI Admin" --type api-key \
  --visa privilege --platform openai \
  --tags admin,admin:openai,provisioning \
  --owner [email protected] --stdin
The --stdin flag replaces the removed --value flag. Credentials are read from stdin in non-interactive mode.

​
Update Provisioning Code

Once admin passports are in the vault, provisionAndCreatePassport() resolves auth automatically: 
// Before: explicit auth from env var
const { credential, passport } = await provisionAndCreatePassport(vault, request, {
  type: 'api-key',
  key: process.env.OPENAI_ADMIN_KEY!,  // plaintext env var
});

// After: auth resolved from vault
const { credential, passport } = await provisionAndCreatePassport(vault, request);

​
3. Update Python Integration Code

​
WisperaToolCredentials

WisperaToolCredentials no longer injects credentials into os.environ. It now provides a get(key) method and clears credentials on context manager exit. 
# Before: credentials injected into os.environ
with WisperaToolCredentials(vault, passports) as creds:
    # os.environ["OPENAI_API_KEY"] was set
    client = OpenAI()

# After: explicit get() method
with WisperaToolCredentials(vault, passports) as creds:
    api_key = creds.get("OPENAI_API_KEY")
    client = OpenAI(api_key=api_key)
    # credentials cleared on exit

​
LangChain and CrewAI Secret Managers

The passphrase parameter is deprecated in WisperaLangChainSecretManager and WisperaCrewAISecretManager. The vault passphrase is now resolved through the standard auth chain (keychain / session token). 
# Before: explicit passphrase
manager = WisperaLangChainSecretManager(passphrase="my-secret")  # DeprecationWarning

# After: passphrase resolved automatically
manager = WisperaLangChainSecretManager()  # uses keychain or session token

​
4. Update idw create Commands

The --value <val> flag has been removed. Use --stdin instead: 
# Before (removed):
idw create --name "My Key" --type api-key --value "sk-..."

# After:
echo "sk-..." | idw create --name "My Key" --type api-key --stdin

# Or interactively (prompts for value):
idw create --name "My Key" --type api-key

​
5. Handle Post-Import Warnings

All idw import paths now warn users to securely delete source files that still contain plaintext credentials. After importing: 
# Import credentials
idw import ./project --all --owner [email protected]

# You'll see a warning like:
# ⚠ Source files still contain plaintext credentials.
# ⚠ Consider securely deleting: .env, config/secrets.json
Follow the guidance to remove or rotate the plaintext originals after confirming the vault import is correct.

​
Migration Checklist

StepActionVerify
1Remove IDW_PASSPHRASE from shell profilesidw auth status shows os-keychain
2Run idw auth loginPassphrase stored in keychain
3Create session tokens for CIidw auth token list shows tokens
4Run idw auth bootstrapAdmin passports created with privilege visa
5Remove admin keys from env varsenv | grep -i admin returns nothing
6Update provisioning codeRemove explicit auth parameter
7Update Python WisperaToolCredentialsUse creds.get() instead of os.environ
8Replace --value with --stdinAll idw create commands updated

​
Next Steps

Authentication

Full reference for passphrase mode, session tokens, and admin passports.

Provisioning

Provisioning with vault-resolved admin credentials.

Security architecture

Updated threat model including session token design.