Credential Management

dbtrail follows a strict policy: credentials are never stored as plaintext. All sensitive values (MySQL passwords, SSH keys) are stored as vault references.

How vault references work

When you register a server and provide a MySQL password:

1. The password is sent over TLS in the API request body
2. dbtrail generates a vault reference (e.g., vault:secret/mysql/production-main)
3. Only the vault reference is stored in the mysql_pass_vault_ref column
4. The plaintext password is never persisted in the database

When the agent needs to connect to MySQL, it retrieves the password from the vault using the stored reference.

Credential columns

Any database column that holds a credential reference uses the _vault_ref suffix convention:

This naming convention makes it easy to identify which columns hold sensitive data and ensures they are never accidentally exposed in API responses.

API key security

API keys follow similar security principles:

• Keys are never stored in plaintext — only the SHA-256 hash is persisted
• The full key is shown to the user exactly once at creation time
• Only the key prefix (e.g., bt_live_a1b) is stored for display purposes
• If the database is compromised, attackers get hashes — not usable tokens

See API Keys for details on key management.

Best practices