docs: add OpenBao secret storage guide

SUMMARY.md

@@ -13,6 +13,7 @@
 * [Getting Started](getting-started/getting-started.md)
 * [Local Deployment](getting-started/local-deployment/README.md)
   * [Platform](getting-started/local-deployment/platform.md)
+    * [OpenBao Secret Storage (Optional)](getting-started/local-deployment/openbao.md)
   * [Studio](getting-started/local-deployment/studio.md)
   * [Mobile SDK](getting-started/local-deployment/mobile-sdk.md)
 * [Cloud Deployment](getting-started/cloud-deployment/README.md)

contribute/setup/service-setup.md

@@ -56,6 +56,10 @@ Please find `your-ip` in the `.env` file, and replace **all occurrences** it wit
 If you want to know more about the environment variables, please refer to `.env.sample` file which is given at root of the repository.
 {% endhint %}
 
+{% hint style="info" %}
+The email (SendGrid) and AWS S3 credentials can optionally be stored in an OpenBao server instead of the `.env` file. See [OpenBao Secret Storage](../../getting-started/local-deployment/openbao.md).
+{% endhint %}
+
 Apart from the already present variables, you need to add few variables generated from the below prerequisites like the [PostgreSQL](service-setup.md#postgresql), [Keycloak](service-setup.md#top), [Sendgrid](service-setup.md#sendgrid), [AWS S3](service-setup.md#aws-s3), etc at the respective steps. 
 
 ### PostgreSQL

getting-started/local-deployment/README.md

@@ -12,7 +12,7 @@ Welcome to the Local Deployment guide for the CREDEBL platform! This section pro
 Before diving into the installation process, it is important to understand the main components that make up the CREDEBL ecosystem. The local deployment will include the following parts:
 
 * **Prerequisites:** Essential software, dependencies, and system configurations that must be set up before starting the installation process.
-* **Platform:** The core of CREDEBL, responsible for managing identities, transactions, and data flow within the system.
+* **Platform:** The core of CREDEBL, responsible for managing identities, transactions, and data flow within the system. Optionally, its credentials can be stored and sourced from an [OpenBao](openbao.md) secret server instead of the `.env` file.
 * **Studio:** A user-friendly interface that enables interaction with the CREDEBL platform, providing tools for administration and data visualization.
 * **Agent:** The service that handles secure communications and interactions with the platform, acting as the middleware between the user and the platform's core functionalities.
 * **Mobile Wallet:** A secure digital wallet that integrates with CREDEBL Platform, allowing users to manage their digital identities, credentials, and transactions in a safe and controlled manner.

getting-started/local-deployment/openbao.md

@@ -0,0 +1,117 @@
+---
+description: Optional secret storage for CREDEBL Platform credentials using OpenBao
+icon: lock
+---
+
+# OpenBao Secret Storage (Optional)
+
+The CREDEBL Platform can source the credentials used by its email and file-storage integrations from an [OpenBao](https://openbao.org) server instead of plain environment variables. OpenBao is a HashiCorp Vault-compatible secrets engine that provides a central, access-controlled store for your API keys and credentials.
+
+{% hint style="info" %}
+OpenBao secret storage is **optional** and **disabled by default**. The Platform continues to work with credentials supplied directly through the `.env` file as described in the [Platform](platform.md) guide.
+{% endhint %}
+
+When enabled, the following credentials can be stored in OpenBao and fetched by the Platform at runtime:
+
+| Credential        | Stored in OpenBao          | Used for                                            |
+| ----------------- | -------------------------- | --------------------------------------------------- |
+| `RESEND_API_KEY`  | `secret/credebl_resend_api_key`  | Sending emails through Resend                  |
+| `SENDGRID_API_KEY`| `secret/credebl_sendgrid_api_key` | Sending emails through SendGrid              |
+| `SMTP_HOST`, `SMTP_PORT`, `SMTP_USER`, `SMTP_PASS` | `secret/credebl_smtp_config` | Sending emails through SMTP |
+| `AWS_ACCESS_KEY`, `AWS_SECRET_KEY` | `secret/credebl_aws_keys` | Internal S3 file storage |
+| `AWS_PUBLIC_ACCESS_KEY`, `AWS_PUBLIC_SECRET_KEY` | `secret/credebl_aws_keys` | Public (logo/URL) S3 storage |
+| `AWS_S3_STOREOBJECT_ACCESS_KEY`, `AWS_S3_STOREOBJECT_SECRET_KEY` | `secret/credebl_aws_keys` | Connection URL / shortened URL S3 storage |
+
+The Platform loads these in two ways:
+
+1. **Startup injection** — every microservice fetches its secrets once during bootstrap and injects them into the process environment before it starts listening.
+2. **Runtime lookup with caching** — email and S3 clients fetch their own credential sets on demand, cached per secret path for 10 minutes, so credentials can be rotated without restarting the service.
+
+## Step 1: Run the OpenBao server
+
+OpenBao is provided as a Docker service in the platform repository.
+
+```bash
+docker compose -f docker-compose.openbao.yml up -d
+```
+
+This starts an OpenBao server on `http://127.0.0.1:8200` with file-backed storage persisted on a named Docker volume, so data survives container restarts. Server settings live in `config.hcl`.
+
+## Step 2: Provision the server
+
+OpenBao starts sealed and uninitialized. Run the one-shot provisioning script from the root of the platform repository:
+
+```bash
+./openbao-init.sh
+```
+
+The script is idempotent and safe to re-run. It:
+
+* Initializes and unseals the server.
+* Enables the KV v2 secrets engine at `secret/`.
+* Enables the AppRole auth method.
+* Creates a `credebl` role scoped to the `credebl_*` secret paths.
+* Stores the secret values found in the matching environment variables.
+* Prints the values to add to your `.env` file:
+
+```
+BAO_URL=http://127.0.0.1:8200
+BAO_SECRET_PATH=secret/data/credebl_resend_api_key
+BAO_ROLE_ID=<generated>
+BAO_SECRET_ID=<generated>
+```
+
+{% hint style="danger" %}
+The script also prints `BAO_UNSEAL_KEY` and `BAO_ROOT_TOKEN`. These are shown **only on the first run** — save them securely, as they are required to unseal the server or log in later. Do not commit them to the repository.
+{% endhint %}
+
+On later runs, pass `BAO_ROOT_TOKEN` (and `BAO_SECRET_ID` to re-print it) so the script can connect to the already-initialized server:
+
+```bash
+BAO_ROOT_TOKEN=<root-token> ./openbao-init.sh
+```
+
+## Step 3: Configure the Platform
+
+Add the following to your `.env` file, replacing `<role-id>` and `<secret-id>` with the values printed by `openbao-init.sh`:
+
+```sh
+# Enable OpenBao secret storage
+ENABLE_BAO=true
+
+# Secret provider: only 'openbao' is supported today
+SECRETS_PROVIDER=openbao
+
+# OpenBao server URL (docker-compose.openbao.yml maps 8200)
+BAO_URL=http://127.0.0.1:8200
+
+# Default KV v2 path fetched at boot and injected into the process environment
+BAO_SECRET_PATH=secret/data/credebl_resend_api_key
+
+# AppRole credentials generated by ./openbao-init.sh
+BAO_ROLE_ID=<role-id>
+BAO_SECRET_ID=<secret-id>
+```
+
+{% hint style="info" %}
+These variables are already present (with placeholder values) in the `.env.demo` file at the root of the platform repository.
+{% endhint %}
+
+## How secrets are stored
+
+The `openbao-init.sh` script writes each credential set only when the matching environment variable is set (non-empty). For example, to store a Resend API key and SMTP settings:
+
+```bash
+RESEND_API_KEY=your-resend-key \
+SMTP_HOST=smtp.example.com \
+SMTP_PORT=587 \
+SMTP_USER=user \
+SMTP_PASS=password \
+./openbao-init.sh
+```
+
+If none of the variables for a given path are set, that path is skipped.
+
+## Disabling OpenBao
+
+To return to plain environment variables, set `ENABLE_BAO` to anything other than `true` (or remove it) and restart the services. The Platform then falls back to the credentials provided directly in the `.env` file.

getting-started/local-deployment/platform.md

@@ -54,6 +54,10 @@ Here is the list of prerequisites we will need for CREDEBL:
     * S3 Bucket Name
     * AWS Region
 
+{% hint style="info" %}
+Instead of placing these credentials directly in your `.env` file, you can optionally store them in an OpenBao server and have the Platform source them at runtime. See [OpenBao Secret Storage](openbao.md).
+{% endhint %}
+
 <details>
 
 <summary>AWS S3 configuration setup </summary>
@@ -86,6 +90,10 @@ Here is the list of prerequisites we will need for CREDEBL:
 * [Sendgrid](https://sendgrid.com/en-us)
   * SendGrid is used for sending email. You must obtain an API key from your SendGrid account.
 
+{% hint style="info" %}
+Your SendGrid API key can optionally be stored in an OpenBao server instead of the `.env` file. See [OpenBao Secret Storage](openbao.md).
+{% endhint %}
+
 <details>
 
 <summary>Sendgrid API key setup steps</summary>