From cb99a314e9be83e586028b9e1c5808ede817ecd2 Mon Sep 17 00:00:00 2001 From: developerjamiu Date: Tue, 30 Jun 2026 09:41:08 +0200 Subject: [PATCH 1/2] docs: Clarify secret access, production storage, and Cloud secrets (#653) --- docs/06-concepts/07-configuration.md | 36 ++++++++++++++++++++++++---- 1 file changed, 32 insertions(+), 4 deletions(-) diff --git a/docs/06-concepts/07-configuration.md b/docs/06-concepts/07-configuration.md index 85a42b65..58bf6642 100644 --- a/docs/06-concepts/07-configuration.md +++ b/docs/06-concepts/07-configuration.md @@ -142,18 +142,46 @@ To define a custom password through an environment variable: export SERVERPOD_PASSWORD_stripeApiKey=sk_test_123... ``` -**Accessing Custom Passwords:** +#### Accessing Secrets in Code -You can then access any custom password (whether defined in the passwords file or via environment variables) in your endpoint code through the `Session.passwords` map: +Secrets are only available on the server. They are never sent to or accessible from your Flutter app. + +Inside an endpoint, read a secret from the [`Session`](sessions) through the `passwords` map: ```dart Future processPayment(Session session, PaymentData data) async { final stripeApiKey = session.passwords['stripeApiKey']; - // Use the API key to make requests to Stripe - ... + // Use the API key to make requests to Stripe. } ``` +`session.serverpod.getPassword('stripeApiKey')` returns the same value. + +Outside of a request, for example during startup in your server's `run` function, read it from the `Serverpod` instance with `getPassword`: + +```dart +// `pod` is the Serverpod instance created in run(). +final stripeApiKey = pod.getPassword('stripeApiKey'); +``` + +This works for built-in and custom secrets alike, whether they come from the passwords file or an environment variable. + +#### Secrets in Production + +A new project gitignores `config/passwords.yaml` and credential files such as `config/firebase_service_account_key.json`, so secrets are not committed by default. Keep production secrets out of source control. + +In production, set secrets through `SERVERPOD_PASSWORD_*` environment variables, or your host's secret manager, rather than a checked-in passwords file. + +#### Secrets on Serverpod Cloud + +On [Serverpod Cloud](/cloud), set these values from the command line instead of editing a passwords file: + +```bash +scloud password set stripeApiKey "sk_live_..." +``` + +Use `--from-file` for long or multi-line values such as a service account JSON. Cloud stores each password encrypted and injects it so `getPassword` reads it exactly as it does locally. See [Passwords, secrets, and environment variables](/cloud/concepts/passwords-secrets-env-vars) for the full reference. + ### Config file example The config file should be named after the run mode you start the server in and it needs to be placed inside the `config` directory in the root of the server project. As an example, you have the `config/development.yaml` that will be used when running in the `development` run mode. From 51679f1d322c59b5584b1c6251a5190c6c7f9f46 Mon Sep 17 00:00:00 2001 From: developerjamiu Date: Wed, 1 Jul 2026 14:02:25 +0200 Subject: [PATCH 2/2] docs: Fix Cloud passwords tier naming and secret/password terminology --- docs/06-concepts/07-configuration.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/06-concepts/07-configuration.md b/docs/06-concepts/07-configuration.md index 58bf6642..45d02bc5 100644 --- a/docs/06-concepts/07-configuration.md +++ b/docs/06-concepts/07-configuration.md @@ -83,7 +83,7 @@ These can be separately declared for each run mode in the corresponding yaml fil ### Secrets -Secrets are declared in the `passwords.yaml` file. The password file is structured with a common `shared` section, any secret put here will be used in all run modes. The other sections are the names of the run modes followed by respective key/value pairs. You can also define custom secrets using [environment variables](#2-via-environment-variables). +Secrets are declared in the `passwords.yaml` file. Serverpod's API reads them with `getPassword`, so this page uses *secret* and *password* interchangeably. The password file is structured with a common `shared` section, any secret put here will be used in all run modes. The other sections are the names of the run modes followed by respective key/value pairs. You can also define custom secrets using [environment variables](#2-via-environment-variables). #### Built-in Secrets @@ -168,13 +168,13 @@ This works for built-in and custom secrets alike, whether they come from the pas #### Secrets in Production -A new project gitignores `config/passwords.yaml` and credential files such as `config/firebase_service_account_key.json`, so secrets are not committed by default. Keep production secrets out of source control. +A new project's `.gitignore` excludes `config/passwords.yaml` and credential files such as `config/firebase_service_account_key.json`, so secrets are not committed by default. Keep production secrets out of source control. In production, set secrets through `SERVERPOD_PASSWORD_*` environment variables, or your host's secret manager, rather than a checked-in passwords file. -#### Secrets on Serverpod Cloud +#### Passwords on Serverpod Cloud -On [Serverpod Cloud](/cloud), set these values from the command line instead of editing a passwords file: +On [Serverpod Cloud](/cloud), the values you read with `getPassword` live in the **Passwords** tier. Set them from the command line instead of editing a passwords file: ```bash scloud password set stripeApiKey "sk_live_..."