Skip to main content

​
Migration Guide

This guide covers migrating from legacy patterns to the current credential architecture.

​
1. Choose Your Authentication Method

ID Wispera supports multiple authentication methods. Choose the one that best fits your environment:
EnvironmentRecommended MethodSetup
Local development (macOS/Linux desktop)OS Keychainidw auth login
CI / HeadlessSession tokensidw auth token create
Containers, WSL, minimal LinuxIDW_PASSPHRASE via .env fileCreate .env with chmod 600
Interactive CLIPromptAutomatic fallback
See the Authentication guide for the full resolution chain and configuration details.

​
Local Development — Use Keychain

Store the passphrase in your OS keychain for seamless access: 
idw auth login
The passphrase is now resolved automatically on every idw command.

​
CI / Headless — Use Session Tokens

For CI pipelines, use 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 Scrypt + AES-256-GCM. Tokens are scoped (labeled), time-limited, and individually revocable.

​
Containers / WSL — Use IDW_PASSPHRASE

For environments without an OS keychain, use IDW_PASSPHRASE via environment variable or .env file: 
# Option A: environment variable
export IDW_PASSPHRASE="my-vault-passphrase"

# Option B: .env file (recommended — more secure)
echo 'IDW_PASSPHRASE=my-vault-passphrase' > .env
chmod 600 .env

​
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 you@company.com --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 / IDW_PASSPHRASE). 
# Before: explicit passphrase
manager = WisperaLangChainSecretManager(passphrase="my-secret")  # DeprecationWarning

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

​
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. Use idw exec for Credential Injection

Instead of exporting credentials as environment variables, use idw exec to inject them into subprocesses securely: 
# Before: credentials in shell environment
export OPENAI_API_KEY="sk-..."
python agent.py

# After: credentials injected per-process, never in the parent shell
idw exec -p "OpenAI Production" -- python agent.py

​
6. 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 you@company.com

# 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
1Choose auth method (keychain, session token, or IDW_PASSPHRASE)idw auth status shows correct source
2Run idw auth login (if using keychain)Passphrase stored in keychain
3Create session tokens for CI (if applicable)idw 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
9Adopt idw exec for credential injectionNo credentials exported in shell profiles

​
Next Steps

Authentication

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

Credential injection

Securely inject vault credentials into subprocesses with idw exec.

Security architecture

Updated threat model including session token design.