Authentication
ID Wispera supports two vault authentication modes. Both ultimately derive the same AES-256-GCM encryption key — they differ only in how the passphrase is resolved.
Authentication Modes
Passphrase Mode (Default)
The recommended mode for local development. The passphrase is resolved through a priority chain:
OS Keychain → Interactive Prompt → IDW_PASSPHRASE env var (deprecated)
The IDW_PASSPHRASE environment variable is deprecated. It still works but emits a deprecation warning. Migrate to idw auth login (keychain) or session tokens (CI).
Session Token Mode (CI / Headless)
For CI pipelines and headless environments where a keychain is unavailable. Session tokens wrap the passphrase using PBKDF2 + AES-256-GCM and are stored in a sidecar file (~/.id-wispera/sessions.json).
Create a session token:
idw auth token create --label "ci-pipeline" --expires 24h
24h, 7d, 30d.
Use the token in CI:
export IDW_SESSION_TOKEN="idwst_..."
idw list # vault unlocks automatically via session token
# List active tokens
idw auth token list
# Revoke a token by hash prefix
idw auth token revoke abc123
The passphrase is always the root recovery path. The session token sidecar (sessions.json) is a convenience layer, never a dependency. If you lose all session tokens, the passphrase still unlocks the vault.
~/.id-wispera/sessions.json file uses a cross-SDK compatible schema:
| Field | Format |
|---|
| Token hash | Hex-encoded SHA-256 |
| Salt | Hex-encoded |
| IV | Hex-encoded |
| Encrypted passphrase | Base64url |
| Created / Expires | ISO 8601 |
| Label | Free-text string |
Auth Status
Check the current authentication state and how the passphrase was resolved:
Example output:
Auth mode: passphrase
Source: os-keychain
Vault: ~/.id-wispera/vault.json
Session tokens: 2 active (1 expiring in 3h)
Admin Passports
Provider admin credentials (AWS access keys, OpenAI admin keys, etc.) are now stored as encrypted passports inside the vault instead of plaintext environment variables.
Each admin passport has:
- Visa type:
privilege
- Tags:
admin, admin:<provider>, provisioning
Bootstrap Wizard
The idw auth bootstrap command is an interactive wizard that collects your provider admin credentials and stores them as encrypted admin passports:
The wizard prompts for each provider’s admin credentials and creates passports with the correct visa type, tags, and platform metadata.
Vault-Resolved Provisioning Auth
The provisionAndCreatePassport() function now optionally resolves auth from the vault when the auth parameter is omitted. It looks up admin passports by matching the admin:<provider> tag:
import { provisionAndCreatePassport } from '@id-wispera/core';
// Auth resolved from vault — no explicit auth parameter
const { credential, passport } = await provisionAndCreatePassport(vault, {
provider: 'openai',
name: 'Coding Agent Key',
humanOwner: '[email protected]',
config: { provider: 'openai', organizationId: 'org-abc123', keyType: 'service-account' },
tags: ['production', 'coding-agent'],
});
Run idw auth bootstrap once to set up admin passports, then all subsequent provisioning calls can resolve auth automatically from the vault.
Cross-SDK Parity
The auth module exists in all three SDKs with identical behavior:
| SDK | Package | Keychain | Crypto |
|---|
| TypeScript | packages/core/src/auth/ | keytar (optional) | Web Crypto API (SubtleCrypto) |
| Python | packages/python/id_wispera/auth/ | keyring (optional) | cryptography library |
| Go | packages/go/pkg/auth/ | Stub (go-keyring not yet wired) | golang.org/x/crypto |
CLI Reference
| Command | Description |
|---|
idw auth login | Authenticate and store passphrase in OS keychain |
idw auth logout | Remove passphrase from keychain |
idw auth status | Show current auth state and source |
idw auth token create [--label <name>] [--expires <duration>] | Create a session token |
idw auth token list | List active session tokens |
idw auth token revoke <hash-prefix> | Revoke a session token |
idw auth bootstrap | Interactive wizard to set up admin passports |
Next Steps
