> ## Documentation Index > Fetch the complete documentation index at: https://docs.parmanasystems.com/llms.txt > Use this file to discover all available pages before exploring further. # Deploy Patterns > In-memory vs Supabase storage, the full environment variable checklist, and how key management actually works: two separate keypairs, one directory, one optional rotation variable. **\[AVAILABLE]** for everything below, this is what actually runs today. Cloud/KMS/multi-instance/HA deployment is \[ROADMAP], see [Roadmap](/roadmap). ## Goal Stand up a real deployment with the storage backend you actually want, and understand exactly which keys the server needs, where they live, and what each one is for. ## Prerequisites * Read [Gateway attestation](/concepts/gateway-attestation), this guide's key management section assumes you know the gateway keypair is separate from the authorization key and why. ## Steps ### 1. Choose a storage provider ```typescript theme={null} // packages/storage/src/StorageFactory.ts switch (configuration.provider) { case "memory": return new MemoryStorageProvider(); case "supabase": return new SupabaseStorageProvider(); case "postgres": throw new Error("Postgres storage provider not implemented."); case "sqlite": throw new Error("SQLite storage provider not implemented."); } ``` Only `memory` and `supabase` have a real class behind them, `postgres` and `sqlite` are declared in the type union and throw immediately at startup, by design, fails closed rather than silently falling back to something else. ```bash theme={null} PARMANA_STORAGE=memory # in-process, non-persistent, no external dependency # or PARMANA_STORAGE=supabase # this repo's committed .env default ``` `PARMANA_STORAGE` is the only variable read for this. An older `DATABASE_PROVIDER` variable existed briefly as a second, disconnected path to the same setting and is now retired: if it's present in the environment, config loading fails at startup naming `PARMANA_STORAGE` as the replacement, rather than silently ignoring it. ### 2. Generate both required keypairs Two, deliberately separate: ```bash theme={null} node_modules/.bin/tsx scripts/generate-keypair.ts --algorithm ed25519 --key-id default npm run generate:gateway-keys ``` Both write into `PARMANA_KEY_DIR` (defaults to `./keys`). `default.*.pem` signs and verifies [execution authorizations](/concepts/execution-authorization). `gateway.*.pem` signs [gateway attestations](/concepts/gateway-attestation). They protect different things and are never the same key, mixing them up is not just a style choice, `assertKeyType` fails closed if you sign with the wrong one for a configured provider. ### 3. Generate a caller API key for every system that will call this API ```bash theme={null} npm run generate:api-key -- --caller-id orchestrator-1 ``` Prints a raw key once, and the hash to add to `PARMANA_API_KEYS`. The raw key is never written to disk by the script and cannot be recovered afterward, hand it to the calling system now. Repeat once per caller (your AI orchestration service, an internal dashboard, anything else that will call this API), and repeat again per caller whenever you rotate a key, see [Rotating a caller's key](#rotating-a-callers-key) below. ### 4. Set the full environment checklist ```bash theme={null} PARMANA_STORAGE=memory # or: supabase PARMANA_POLICY_DIR=/absolute/path/to/policies PARMANA_KEY_DIR=/absolute/path/to/keys PARMANA_GATEWAY_KEY_ID=gateway # optional, defaults to "gateway" VENDOR_PAYMENT_TOKEN=... # credential for the one wired connector PRIMARY_SIGNATURE_PROVIDER=ed25519 # or: dilithium3, needs Node >= 24 HASH_PROVIDER=sha256 PARMANA_API_KEYS=[{"callerId":"orchestrator-1","keyHash":"..."}] # from step 3, one entry per key ``` `PARMANA_API_KEYS` is a JSON array. Multiple entries may share the same `callerId`, that is how rotation works, see below. The server refuses to start with this unset or empty, unless `PARMANA_AUTH_DISABLED=true` is set explicitly for local development, see [Caller authentication](#caller-authentication). ### 5. Run it ```bash theme={null} npm run dev ``` ## Verify Confirm the server actually started and is enforcing what you expect: ```bash theme={null} curl http://localhost:3000/health # {"status":"UP"} ``` If `PARMANA_KEY_DIR` is missing `gateway.private.pem`, the server refuses to start with a message naming the exact missing path, it does not start in a degraded, gateway-less mode, there is no such mode, see [The gateway](/concepts/the-gateway). ## What `PARMANA_GATEWAY_KEY_ID` is for Rotating the gateway's key without touching `default.*.pem` or restarting with a completely new key directory: generate a second gateway keypair under a different ID (for example `gateway-v2`), verify it works, then flip `PARMANA_GATEWAY_KEY_ID=gateway-v2` and restart. The old `gateway.*.pem` files can stay in place until you're confident in the rotation, they simply won't be read. ## Caller authentication Every route except `GET /health` requires a caller credential: a bearer key generated in step 3, sent as `Authorization: Bearer `. Only a SHA-256 hash of each key is ever held by the server, comparisons run in constant time against that hash, and the raw key is never logged or written to disk anywhere in this codebase. **This is only safe over TLS.** A bearer key sent over plaintext HTTP is readable by anything that can observe the connection. Terminate TLS in front of this server (a reverse proxy, load balancer, or service mesh sidecar in your own infrastructure, since Parmana does not run a hosted service for you), and never expose the API on plaintext HTTP outside `localhost`. This is not a suggestion, it is the entire security value of the bearer-key scheme. Caller authentication is a distinct layer from everything else Parmana does. It runs first, before a Business Transaction is even constructed, and answers only "should this HTTP request be entertained at all." It is independent of, and cannot substitute for, [policy evaluation](/concepts/policies-and-the-decision) (a well-authenticated caller submitting a policy-rejected transaction is still rejected) or [gateway attestation](/concepts/gateway-attestation) (which proves the gateway itself released a specific execution, not who called the API). Keeping these layers separate is deliberate, see [How Parmana thinks](/how-parmana-thinks). ### Rotating a caller's key No downtime, no restart required beyond a config reload: 1. Generate a new key for the same `callerId`: `npm run generate:api-key -- --caller-id orchestrator-1`. 2. Add the new `{ callerId, keyHash }` entry to `PARMANA_API_KEYS` alongside the old one. Both are active during migration. 3. Hand the new raw key to the caller, confirm it works. 4. Remove the old entry from `PARMANA_API_KEYS`. The old key is now revoked and stops authenticating immediately on the next config reload. ### Upgrading beyond static keys Caller authentication is implemented behind one interface, `CallerAuthenticator` (`packages/api/src/auth/CallerAuthenticator.ts`), with `StaticKeyAuthenticator` as the only implementation today. If your environment requires mutual TLS instead (common in banks that already run internal PKI for service-to-service traffic), that is a second class implementing the same interface, swapped in at one place (`packages/api/src/bootstrap/createCallerAuthenticator.ts`), not an architecture change: the middleware, the audit trail, and every route's behavior stay exactly as documented above. ### Disabling authentication (local development only) ```bash theme={null} PARMANA_AUTH_DISABLED=true ``` Skips caller authentication entirely and logs a loud warning at startup every time. This exists for local development and running the tutorials, and must never be set in a real deployment, doing so removes the only authentication this API has. ## What this deployment does not give you * **No KMS/HSM.** Both private keys are files on disk, exactly the exposure that produced the incident noted on [Security](/security/overview). `KeyProviders` declares `aws-kms`, `azure-key-vault`, `gcp-kms`, and `hsm` as config values with zero implementing classes, setting `KEY_PROVIDER` to one of these today does nothing useful. * **Single process, single instance.** No shared `NonceStore` across replicas, a fleet of these processes would each accept the same authorization once, not once fleet-wide (CLAIMS.md 3.2). * **Only one connector registered.** `vendor-payment`, a reference mock, see [Add a connector with the Connector SDK](/guides/add-a-connector) for what adding another requires today. ## Troubleshoot * **`Gateway private key not found`.** Run `npm run generate:gateway-keys`, or confirm `PARMANA_KEY_DIR` points at the directory you actually generated into. * **`Key directory does not exist`.** `PARMANA_KEY_DIR` (or the `./keys` default) must exist before the server starts, `FileKeyProvider` doesn't create it. * **Config loading fails naming `DATABASE_PROVIDER`.** Remove that variable from your environment, use `PARMANA_STORAGE` instead, see step 1. * **`Postgres storage provider not implemented.`** Expected, `postgres` and `sqlite` are declared but not built, use `memory` or `supabase`. * **`No caller authentication keys are configured`.** `PARMANA_API_KEYS` is unset or `[]`. Generate a key (step 3) and add it, or set `PARMANA_AUTH_DISABLED=true` for local development only. * **`401 authentication required` on every request.** Missing or malformed `Authorization` header, confirm you're sending `Authorization: Bearer ` with the exact raw key from step 3, not the hash. ## Next What `PRIMARY_SIGNATURE_PROVIDER` actually changes, and its real cost. What's designed but not built yet for production deployment: KMS, HA, network enforcement.