Vault & Credentials

TokenHub includes an AES-256-GCM encrypted vault for storing provider API keys securely. Provider credentials are encrypted at rest and only decrypted in memory when the vault is unlocked.

Vault password vs. admin token: The vault password is not the same as your admin token. The admin token authenticates HTTP requests to the admin API. The vault password derives the encryption key used to protect stored credentials. Both are required in a production deployment: the admin token to access the API, and the vault password to decrypt provider keys.

How It Works

1. An administrator sets a vault password when first configuring TokenHub
2. The password is run through Argon2id key derivation (OWASP-recommended parameters) to produce an encryption key
3. Provider API keys are encrypted with AES-256-GCM and stored in SQLite
4. A random salt is generated per vault instance and persisted alongside the encrypted data
5. After server restart, the vault must be unlocked with the same password before provider requests can be made

Vault States

Auto-Unlock (Headless)

Set TOKENHUB_VAULT_PASSWORD to unlock the vault automatically at startup. This is required for automated/headless deployments where no operator is present to enter the password interactively.

export TOKENHUB_VAULT_PASSWORD="your-secure-password"

On first boot this also initializes the vault, so no interactive setup is needed.

Operations

Unlock the Vault

Via the admin UI (recommended for first-time setup — the UI asks for the password twice to prevent typos), or via API/CLI:

tokenhubctl vault unlock "your-secure-password"

Or via curl:

curl -X POST http://localhost:8080/admin/v1/vault/unlock \
  -H "Content-Type: application/json" \
  -d '{"admin_password": "your-secure-password"}'

Response:

{"ok": true}

Lock the Vault

curl -X POST http://localhost:8080/admin/v1/vault/lock

Response:

{"ok": true, "already_locked": false}

Rotate the Vault Password

Re-encrypts all stored credentials with a new password:

curl -X POST http://localhost:8080/admin/v1/vault/rotate \
  -H "Content-Type: application/json" \
  -d '{
    "old_password": "current-password",
    "new_password": "new-secure-password"
  }'

This operation is atomic — all credentials are re-encrypted in a single transaction.

Auto-Lock

The vault automatically locks after 30 minutes of inactivity. Every successful credential access resets the timer.

When the vault auto-locks:

• In-flight requests that have already retrieved credentials continue normally
• New requests will fail with a provider error until the vault is unlocked again
• An audit log entry is recorded

Credential Storage

When you register a provider with cred_store: "vault", TokenHub stores the API key encrypted in the vault under the key provider:{provider_id}:api_key.

The credential lifecycle:

1. Admin provides API key when creating/updating a provider
2. Key is encrypted and stored in the vault
3. Key is also persisted (encrypted) in the database for recovery after restart
4. When the vault is unlocked, the salt and encrypted blob are loaded from the database
5. Keys are decrypted only in memory

Security Parameters

Best Practices

1. Use a strong vault password: At least 16 characters with mixed case, numbers, and symbols
2. Use TOKENHUB_VAULT_PASSWORD for automated deployments so the vault unlocks on restart
3. Rotate regularly: Use the rotate endpoint to change the vault password periodically
4. Monitor auto-lock: Set up alerts if the vault locks unexpectedly during business hours
5. Backup the database: The vault salt and encrypted blob are stored in SQLite. Back up the database file to ensure credential recovery
6. Network isolation: Restrict access to vault admin endpoints to trusted networks