Build against a store
that can't read you.

The zero-knowledge model.

secret-lab is an API-only secrets store. You keep key → value entries in vaults, where each value is an opaque document the server never parses. It can be JSON for a multivalue record, plain text or raw binary. The server stores only ciphertext and the verifiers it needs to authenticate you. It holds no key that decrypts any secret.

That single fact shapes the whole API. Your client generates keys, derives them, encrypts and decrypts. The server takes ciphertext in and hands ciphertext back. A full compromise of the database or the running process yields ciphertext only, for every secret, with no exceptions. The cryptography that makes this true, Two-Secret Key Derivation over an X25519 keypair hierarchy, is documented in the security model.

Accounts.

An account is the unit of identity. Enrollment is self-serve: a single POST /v1/enroll mints an empty account shell and returns a one-time claim, with no operator approval in the loop. Your client then runs a one-time init that consumes the claim and uploads your public material. The two secrets that unlock the account, a memorized passphrase and a 256-bit Secret Key generated on your device, never reach the server.

What the server stores for an account is the SRP verifier and its salt, the passphrase KDF salt, the account public key and the account private key wrapped under your Account Unlock Key (the AUK). None of it decrypts anything on its own. An account moves through three states: pending after enrollment and before setup, active once init consumes the claim, and suspended if an operator suspends it.

Vaults and items.

A vault is a container of secrets with its own symmetric vault key, the VK. Items inside it are encrypted under that VK. The owner's copy of the VK is wrapped to their account public key, so unlocking the account keypair gives access to the vault. You can share a vault by wrapping its VK to another account's public key.

An item is a single key → ciphertext pair. The server addresses it by a blind index called the key_ref, computed client-side as HMAC-SHA256(index_key, normalize(key_name)). Plaintext key names never reach the server. Writes are latest-only, so a PUT overwrites in place with no version history, and deletes leave a soft-delete tombstone.

Key slots.

The same vault is reachable through different front doors called key slots. A human slot wraps the account private key under the Account Unlock Key and authenticates with SRP-6a. A machine slot wraps a vault key under a key derived from a single machine secret and is scoped to one vault. A share slot is a vault key wrapped to another account's public key. Everything below the account and vault key is identical regardless of which slot did the unlocking. The slots differ only in how you authenticate and how your copy of the key is wrapped.

Machine credentials.

A machine credential lets a headless consumer, a CI job or a running service, reach one vault with no human in the loop. The client generates a single machine key (MK) and from it derives two values. HKDF(MK, "auth") is the auth secret sent to the server, which stores it as an Argon2id hash. HKDF(MK, "unwrap") never leaves the machine and unwraps that slot's wrapped vault key.

Because the server only ever sees the auth secret, and stores even that hashed, it cannot recover the machine key or the unwrap key. Machine slots are scoped to a single vault and independently revocable. Losing a machine key costs nothing. Mint a new credential and delete the old slot.

Bootstrap in two calls.

Going from nothing to an active account is two HTTP calls. POST /v1/enroll hands back an account id and a one-time claim. POST /v1/accounts/init consumes that claim and uploads the public and wrapped material your client generated locally. After that you authenticate and start reading and writing secrets. The client does the crypto for both; the curl below shows only the wire so you can see what crosses it.

# 1. self-serve enrollment: mint an account shell + one-time claim
curl -s -X POST https://secrets.lab.stratus5.net/v1/enroll
# → { "account_id": "acct_9f3...", "claim": "acct_9f3...:tok_b71..." }

# 2. init: the client derives the AUK from passphrase + Secret Key, wraps the
#    account keypair and first vault key, and uploads only ciphertext + verifiers.
curl -s -X POST https://secrets.lab.stratus5.net/v1/accounts/init \
  -H 'content-type: application/json' -d @init.json
# → { "account_id": "acct_9f3..." }   the account is now active

Conventions.

A few rules hold across every endpoint, so they are stated once here rather than repeated on each card.

• Transport. HTTPS only, terminated at the edge. All paths hang off https://secrets.lab.stratus5.net.
• Encoding. Request and response bodies are JSON. Binary fields (keys, salts, ciphertext, nonces, wrapped blobs) are standard base64 inside the JSON. The one exception is the {key_ref} path segment, which is base64url without padding because it sits in the URL.
• Auth headers. Admin endpoints take X-Admin-Key. Authenticated endpoints take Authorization: Bearer <token> where the token came from an auth call. Enrollment, init, auth-params and the SRP and machine auth calls are public.
• IDs are client-chosen where it matters. The account id is fixed by the claim, but vault_id, the secret's key_ref and a machine credential_id are minted by the client so the server never needs to hand back an identifier you then have to map to a local secret.
• Errors. Every error is { "error": "<reason>" } with a matching HTTP status. The full catalogue is under errors.

Enrollment.

One public endpoint, no authentication, no admin key. It mints an empty account shell and returns a one-time claim immediately. There is no approval step and no application to poll. The only gate is a per-IP rate limit, which is safe because the shell is inert until init consumes the claim.

{
  "account_id": "acct_...",
  "claim":      "acct_...:tok_..."   // one-time, consumed by init, never returned again
}

Account setup.

One-time setup authorised by the claim. By the time you call this, the client has generated the Secret Key locally as the Emergency Kit, taken a passphrase, derived the Account Unlock Key, generated the account keypair, and minted the first vault and its key. This call uploads the public and wrapped material, all of it ciphertext or opaque, consumes the claim and flips the account to active. The first vault is created in the same call so the account is usable the moment init returns.

{
  "claim":               "acct_...:tok_...",
  "account_id":          "acct_...",       // must match the id inside the claim
  "account_pubkey":      "<base64>",
  "enc_account_privkey": "<base64>",       // account private key wrapped under the AUK
  "kdf_salt":            "<base64>",       // passphrase KDF salt (Argon2id)
  "auth_verifier_salt":  "<base64>",       // SRP verifier salt
  "auth_verifier":       "<base64>",       // SRP-6a verifier v = g^x, computed client-side
  "first_vault": {
    "vault_id":   "vault_...",            // client-chosen
    "wrapped_vk": "<base64>"             // first vault key wrapped to account_pubkey
  }
}

{ "account_id": "acct_..." }

{ "kdf_salt": "<base64>" }

Authentication.

Two paths, both ending in a bearer token. Humans run SRP-6a over the passphrase and Secret Key, neither of which crosses the wire. Machines present a one-way auth secret derived from their machine key. Both return a token and an expires_at; attach the token as Authorization: Bearer <token> on every authenticated call after that. See sessions for lifetime and scope.

{ "account_id": "acct_...", "a": "<base64>" }   // a = g^a mod N, client public ephemeral

{
  "handle": "srp_...",      // pass back to finish; one-shot, 2-minute TTL
  "salt":   "<base64>",     // SRP verifier salt
  "b":      "<base64>"      // server public ephemeral
}

{ "handle": "srp_...", "m1": "<base64>" }

{
  "m2":                  "<base64>",   // server proof
  "token":               "...",        // bearer token for subsequent calls
  "expires_at":          "<RFC3339>",
  "account_pubkey":      "<base64>",
  "enc_account_privkey": "<base64>"    // AUK-wrapped, the client unwraps it locally
}

{ "credential_id": "mach_...", "auth_secret": "<base64>" }

{
  "token":      "...",
  "expires_at": "<RFC3339>",
  "vault_id":   "vault_...",    // the one vault this credential reaches
  "wrapped_vk": "<base64>"      // VK wrapped under HKDF(MK,"unwrap")
}

Vaults.

Human-session operations. A vault is a container with its own symmetric key, the VK. The client generates the VK, wraps it to the account public key and uploads only the wrapped form; the server never holds an unwrapped key. Listing returns each vault you can reach with its wrapped VK so the client can unwrap it under the account private key.

{
  "vault_id":   "vault_...",     // client-chosen
  "wrapped_vk": "<base64>"      // VK wrapped to account_pubkey
}

{ "vault_id": "vault_..." }

[
  { "vault_id": "vault_...", "wrapped_vk": "<base64>" }
]

Secrets.

Session calls, ciphertext both directions, all scoped to a vault id in the path. Each secret is addressed by its key_ref, a blind index the client computes as HMAC-SHA256(index_key, normalize(key_name)) and encodes base64url (no padding) for the URL. The server stores and serves the ciphertext, nonce, algorithm tag, a protection marker and an optional encrypted key name. It never sees a plaintext key or value. A machine session may touch only the one vault it is scoped to; a human session may touch any vault it has access to.

{
  "ciphertext":   "<base64>",    // the opaque encrypted document
  "nonce":        "<base64>",    // random per encryption
  "alg":          "xchacha20poly1305",
  "protection":   "vault",            // opaque marker describing how the item was wrapped
  "enc_key_name": "<base64>"     // optional: key name encrypted under VK, for list-and-decrypt
}

{ "status": "stored" }

{
  "ciphertext":   "<base64>",
  "nonce":        "<base64>",
  "alg":          "xchacha20poly1305",
  "protection":   "vault",
  "enc_key_name": "<base64>"
}

{ "status": "deleted" }

[
  {
    "key_ref":      "<base64>",
    "enc_key_name": "<base64>",
    "updated_at":   "<RFC3339>"
  }
]

Machine credentials.

A machine credential is a slot scoped to a single vault that a headless consumer authenticates with, no human keypair involved. Minting one is a human-session call on the vault. The client generates the machine key locally, derives the auth secret and the unwrap key, wraps the VK under the unwrap key, and uploads the verifier material and the wrapped VK. The machine key itself never reaches the server; you hand it to the consumer out of band.

{
  "credential_id":      "mach_...",   // client-chosen
  "label":             "ci-prod",
  "auth_verifier_salt": "<base64>",
  "auth_verifier":      "<base64>",    // Argon2id verifier over HKDF(MK,"auth")
  "wrapped_vk":         "<base64>"     // VK wrapped under HKDF(MK,"unwrap")
}

{ "credential_id": "mach_..." }

{ "status": "revoked" }

Admin.

Operator endpoints, gated by a static X-Admin-Key header rather than a session. They never touch plaintext or any unwrapping key; they provision shells, suspend accounts and report metadata sizes. Stats are sizes and counts only, never values. The admin key is held server-side by the operator console and is not something an ordinary client ever needs.

{ "account_id": "acct_...", "claim": "acct_...:tok_..." }

{ "status": "suspended" }

{ "account_id": "acct_...", "secrets": 12, "bytes": 40960 }

Sessions.

Both auth paths return a token and an expires_at. Attach the token on every authenticated call as an HTTP header:

Authorization: Bearer <token>

The server stores only a hash of the token, never the token itself, and checks expiry on each call. A request with a missing, unknown or expired token gets 401. A human session can reach any vault the account has access to. A machine session is pinned to the single vault its credential is scoped to, and reaching past it returns 403. Some endpoints additionally require a human session: creating a vault, minting or revoking a machine credential. A machine token on those returns 403.

Rate limits.

Limits are per-IP and, on the auth paths, also per-account or per-credential. Hitting one returns 429 with { "error": "too many attempts" } (or too_many on enrollment). Back off and retry.

• Enrollment. A fixed window per IP caps how many account shells one source can mint. This is the only gate on the unauthenticated mint path.
• SRP start. A fixed window per IP caps the expensive modular-exponentiation work, on top of the failure limiter.
• Auth failures. Repeated failed SRP or machine auth trips a failure limiter keyed by IP and by account or credential. A clean success resets it, so normal use never sees it.

The edge sits behind nginx, which forwards the real client address. Per-IP limiting is defence in depth; the per-account and per-credential limits are the controls that cannot be spoofed by rotating source addresses.

Errors & help.

Every API error is a JSON object with one field and a matching HTTP status:

{ "error": "<reason>" }

Client-side crypto failures

These never reach the server, because the server never decrypts. The one that matters most is an AEAD authentication failure on decrypt. If the ciphertext, nonce or bound AAD has been altered, Poly1305 rejects the tag and decryption fails closed: the client gets an error and no plaintext. The same happens if a blob is lifted to a different key_ref, since the AAD binds vault_id ∥ key_ref and no longer matches. A wrong passphrase or Secret Key produces the wrong Account Unlock Key, so the account private key fails to unwrap. None of these are server errors. They are the zero-knowledge design failing safe on your side.

Testing.

The property worth testing is the round trip: a value you encrypt, store, fetch and decrypt comes back byte-for-byte equal, and a value that was tampered with on the way fails to decrypt rather than returning wrong plaintext. You can prove both against a local instance.

Round-trip check

Point your client at a local server, authenticate, then run one cycle through the API. Assert equality at the end.

# against a local instance
1.  authenticate                          # SRP (P + SK) or machine auth → token
2.  plaintext = random bytes
3.  ref = base64url(HMAC(index_key, normalize("test/roundtrip")))
4.  PUT  /v1/vaults/{vault}/secrets/{ref} # client encrypts under VK, uploads ciphertext+nonce
5.  GET  /v1/vaults/{vault}/secrets/{ref} # pull the stored blob back
6.  decrypted = client decrypts the returned blob
7.  assert decrypted == plaintext        ✓ round trip holds

Tamper check

Now flip a bit and confirm the failure is a hard one. Decryption must fail closed, never hand back altered plaintext.

1.  GET  /v1/vaults/{vault}/secrets/{ref}   # fetch the stored ciphertext
2.  flip one byte of ciphertext (or nonce)
3.  attempt client decrypt
4.  assert decrypt FAILS                ✓ Poly1305 rejects the tag
5.  assert no plaintext is returned     ✓ fails closed

# replay check: move a valid blob to a different key_ref
6.  PUT the unmodified blob at a different {ref2}
7.  GET  /v1/vaults/{vault}/secrets/{ref2}; attempt decrypt
8.  assert decrypt FAILS                ✓ AAD binds the original key_ref

The full walk-through, in Go, Java, Node and .NET, is on the quickstart page.