# Secret Manager

Secret Manager keeps API keys, database URLs and other secrets end-to-end encrypted. Store them once and fetch them at runtime everywhere, while the platform itself can never read them.

## The zero-knowledge model

Encryption happens **on your side**. Every value is encrypted client-side with AES-256-GCM under a per-app **Master Encryption Key (MEK)**; the MEK itself is stored wrapped (encrypted) under your **App Secret**, which never leaves your machines. The server holds ciphertext + IVs + auth tags, nothing decryptable. Losing the App Secret means the data is unrecoverable by design.

## Concepts

| Concept | What it is |
|---------|-----------|
| **App** | A container of secrets (one service or product), identified by `appId`. |
| **Environment** | `development` / `staging` / `production`; each variable belongs to one. |
| **App Secret** | Client-held key that unwraps the MEK. Never sent to the API. |
| **MEK** | The key your variables are actually encrypted with, fetched wrapped and unwrapped locally. |
| **API key** | A normal platform key with `secret-read` scope. It authorizes *fetching ciphertext*, nothing more. |

## Three ways to consume secrets

1. **Dashboard**: create apps, add variables, share across apps with inheritance links.
2. **This REST API**: your service fetches the wrapped MEK once and the encrypted variables per environment, then decrypts in memory.
3. **The `nism` CLI**: wraps the whole fetch + decrypt flow for local dev and CI (guide below).

## Using this API

Fetch encrypted secrets at runtime without hardcoding them in your application.

**Scope required:** `full-access` or `secret-read`

**All requests use:** `x-api-key: {{apiKey}}`

**How it works:**
1. Store secrets in the merchant dashboard at `/dashboard/org/[orgId]/secret-manager`
2. Your app fetches the encrypted master key (MEK) at startup
3. Decrypt the MEK using your App Secret (stored securely server-side)
4. Fetch encrypted variables; decrypt them locally with the MEK

Secrets are **never returned in plaintext**: everything is encrypted in transit and at rest.

**App Secret vs API key**
- The **App Secret** is a per-app value shown once in the dashboard. It is used to decrypt the MEK client-side.
- The **API key** (`x-api-key`) is the central key that authorises the fetch. Both are required.

**Rate limit:** 50 requests/hour for `GET master-key`

**GET /api/v1/secret-manager/apps/{appId}/master-key**: Get encrypted master key (fetch id `endpoint:6ae152d083f212a997c813bd`)

**GET /api/v1/secret-manager/apps/{appId}/variables**: Get encrypted variables (fetch id `endpoint:6ae152d083f212a997c813be`)