User vs Framework Secrets
tsdevstack manages two categories of secrets: those the framework generates automatically, and those you provide. Understanding the difference helps you know what to configure and what to leave alone.
Framework-Managed Secrets
These secrets are generated automatically when you run npx tsdevstack generate-secrets. You should not edit them directly.
Database Credentials
Each service with a database gets unique credentials:
DB_{SERVICE}_USERNAME- The local database owner, named after the service (for exampleauth-service). It owns the tables and is the Postgres container's admin user.DB_{SERVICE}_PASSWORD- Its cryptographically secure random passwordDATABASE_URL- The connection string the running service uses, as<service>_app, a user that reads and writes rows only. Its password lives in this URL.MIGRATION_DATABASE_URL- The owner's connection string, for migrations and Prisma's tools
These are regenerated only on first run or if deleted. The framework preserves them across subsequent regenerations. See Database users.
JWT Keys
When using authentication templates, the framework generates RSA key pairs:
JWT_PRIVATE_KEY_CURRENT- For signing tokensJWT_PUBLIC_KEY_CURRENT- For verifying tokens- Previous key versions for rotation support
These are preserved across regenerations, so existing tokens stay valid. They live in the auth service's scope, with REFRESH_TOKEN_SECRET, BCRYPT_ROUNDS and ADMIN_EMAILS. Only the auth service can read them, so only it can sign tokens.
Service API Keys
For service-to-service authentication:
AUTH_SERVICE_API_KEYBFF_SERVICE_API_KEYOFFERS_SERVICE_API_KEY- (One per backend service)
Each service also receives an API_KEY alias pointing to its own key: secrets.get('API_KEY') in auth-service reads AUTH_SERVICE_API_KEY, locally and on every cloud provider.
These are preserved across regenerations to maintain service-to-service authentication.
Service URLs
For local development:
AUTH_SERVICE_URL-http://localhost:3001BFF_SERVICE_URL-http://localhost:3003- (Based on configured ports)
In production, these are automatically updated to actual cloud URLs after deployment.
Infrastructure Secrets
REDIS_PASSWORD- Redis authentication (hardcoded asredis_passfor local development)KONG_TRUST_TOKEN- API gateway trust token (preserved across regenerations)KONG_FRONTEND_TOKEN- Proves to the gateway that a visitor address comes from your Next.js frontend. Given to the gateway and every Next.js app; preserved across regenerations. See Client addressesREFRESH_TOKEN_SECRET- Token encryption key, in the auth service's scope. Preserved across regenerations.
User-Supplied Secrets
These are secrets you must provide. Add them to .secrets.user.json.
Third-Party API Keys
Any external service you integrate with, in the section of the service that calls it:
A key every service needs goes in the top-level secrets object instead. See Adding Your Own Secrets.
Configuration Overrides
Some configuration values have sensible defaults that the framework pushes automatically during cloud-secrets:push. You can override them locally in .secrets.user.json or in the cloud with cloud-secrets:set:
To override in the cloud:
External OIDC Provider
If you're NOT using the built-in auth template and instead use an external OIDC provider (Auth0, Cognito, etc.):
This is only needed when you've disabled the auth template. See Escape Hatches for details.
Adding Your Own Secrets
Step 1: Define the Secret
Where you put the value decides which backend services can read it. A secret one service needs goes in that service's section. Only that service can read it:
A secret every backend service needs goes in the top-level secrets object, the shared scope:
Step 2: Regenerate
Step 3: Access in Code
A service looks a key up in its own scope and in shared, and its own value wins when the key is in both. See How Secrets Work.
Common Patterns
Sharing a Secret Across All Backend Services
Put it in the top-level secrets object. Every backend service reads the shared scope, so no list is needed.
Frontend-Only Secrets
Add to the frontend section:
Different Values Per Environment
For local development, define values in .secrets.user.json. For cloud environments, use cloud-secrets:set:
The command prompts for the value, masked, so it stays out of your shell history. --service puts it in that service's scope. Leave it out for a shared secret.
What Not to Do
Do Not Edit Framework Secrets
The .secrets.tsdevstack.json file is regenerated on every generate-secrets run. While critical values (JWT keys, API keys, database credentials) are automatically preserved, any manual edits to this file will be lost. Always use .secrets.user.json for customizations.
Do Not Commit Secrets
All secrets files are gitignored. If you find yourself wanting to commit a secret, you are doing something wrong.
Do Not Use process.env in Backend Services
Always use SecretsService:
Do Not Hardcode Secrets
Even for testing, use the secrets system:
Quick Reference
Partner API keys are not secrets of your project: they are created at runtime through the auth-service admin API and stored hashed in Postgres and Redis, never in secrets files or the cloud secret manager. See API Keys.