Philosophy

ScaiVault makes a handful of opinionated choices. Most of them follow from one observation: secret management goes wrong when it's treated as a storage problem. It's a lifecycle problem.

Secrets have lifecycles, not just values#

A password is not just "the string hunter2". It's a string that was created at some time, will expire, will rotate, is accessed by some set of identities, and may have been compromised at some point. ScaiVault's data model is version-first: writing a secret doesn't overwrite, it appends. You can always answer "what was the value on Monday" and "who read it between then and now".

This is why there is no PUT ... overwrite=true flag. A write is always a new version. If you need to look at the previous value, query the previous version. If you need to reduce storage, configure max_versions on the secret.

Paths, not IDs#

Secrets live at paths — environments/production/salesforce/api-key — not opaque UUIDs. Paths are the API's primary key. This has consequences:

• Access policies can be written in terms of the business meaning (environments/production/**), not identity tables.
• Migrating from HashiCorp Vault is mostly a rename: the mental model is the same.
• Secrets sort hierarchically in the UI and in listings, which matches how people think about them.

The tradeoff: renaming a path is a heavier operation than renaming an ID would be (it creates a new secret and migrates references). We accept that cost because most secrets never get renamed.

Policies match paths, not secrets#

You don't bind a policy to a specific secret. You bind it to a path pattern. environments/production/** matches every secret under environments/production/, including ones that don't exist yet. When a developer creates a new secret in that path, access controls apply automatically — no one has to remember to rebind.

This means policies are a contract about where secrets go, not about which secrets exist. That's also why path conventions matter: inconsistent paths fight the policy model.

Rotation is the default, not an afterthought#

Most secrets in most systems aren't rotated because rotation is hard: you have to coordinate the cutover, you might break consumers, you need to audit it. ScaiVault's rotation model takes those problems head-on:

• Grace periods. The old value stays readable for a configurable window after rotation, so long-running jobs and slow consumers don't break.
• Webhooks before and after. Subscribe to rotation.due to prepare, secret.rotated to pick up the new value.
• Scheduled, audited, idempotent. Rotation policies run on a cron. The audit log shows every rotation with before/after versions.

The bar for "I should rotate this secret" is lower when rotation is this cheap.

Short-lived over long-lived#

A static database password is a liability. Ideally no one has the database root password; when the app needs to talk to the database, it asks ScaiVault for a credential with a one-hour lifetime, uses it, and lets it expire.

ScaiVault's dynamic secrets engines make this practical for databases (PostgreSQL, MySQL, MongoDB, Redis), cloud IAM (AWS, Azure, GCP), and SSH. A long-lived master credential stays in one place — ScaiVault — and everything else is ephemeral. If a key leaks, its blast radius is one hour and one lease.

Audit is a contract, not a feature#

Every read, write, delete, rotation, policy change, and identity lookup is written to the audit log. The log is append-only and includes request ID, identity, source IP, user agent, resource path, and latency. This is non-optional — you can't turn it off per-secret, because the value of an audit log depends on nothing being excluded.

"Why did prod blow up at 03:47" is a question that can be answered from the audit log alone, without running SQL on a shared database or parsing application logs.

Federation over migration#

Moving all your secrets into ScaiVault in one weekend is a bad idea. ScaiVault supports federation: it can front an existing HashiCorp Vault, AWS Secrets Manager, Azure Key Vault, or GCP Secret Manager, and serve reads through the ScaiVault API without the secrets physically moving. You migrate one path prefix at a time, verify it works, then cut over.

This is deliberate. The right answer for an existing fleet is not "rip out Vault" — it's "let ScaiVault be the one API in front of it until you're ready to move the data."

Boring defaults#

• JSON over everything else. No custom binary protocols.
• Bearer tokens in Authorization headers. No cookies, no custom schemes.
• ISO 8601 timestamps. UTC only.
• Cursor-based pagination. No page numbers.
• Stable error codes. No HTTP-status sniffing.

When ScaiVault does something unusual, there's a reason. When it doesn't, it does the boring thing on purpose.

What's next#

• Architecture — how the pieces fit together.
• Quickstart — start using it.
• Secrets — the secret data model in detail.