Secrets
Store API keys, passwords and tokens per environment, and read them safely from your code.
Secrets keeps your workspace's sensitive values — API keys, passwords, tokens, connection strings — encrypted and out of your code. Each environment has its own set, so dev and prod can use different keys. Every time someone reveals a secret's value, it's recorded in the activity log.
Before you start
| To | You need |
|---|---|
| See which secrets exist | Member role or above |
| Reveal a value, or add and change secrets | Writer, Admin or Owner |
| Delete a secret | Writer, Admin or Owner |
Add a secret
Open Secrets
Go to Data → Secrets, and pick the workspace and environment at the top of the page.
Add it
Click Add secret, enter a key, such as STRIPE_API_KEY, and its value, then save. Keys are unique within an environment.
gf secrets set STRIPE_API_KEY - # paste the value, then press Ctrl+D
gf secrets lsReading the value with - keeps it out of your shell history. Add -e <environment-id> to choose the environment.
Values are hidden in the list. To see one, click the eye icon; the reveal is logged. Never paste a revealed value into chat or email.
Some secrets are created and managed by Groundfloor, such as the credentials of a managed database. They're marked in the list and can't be edited or deleted there. The workspace's own data API key is marked (managed) and can't be revealed at all.
Use a secret in your code
| Your code | How it reads secrets |
|---|---|
| A Coderunner | At runtime from the Secrets API, with an M2M token that has Read secrets. See Configuration and secrets |
| A Shell app | Never directly: browser code is visible to everyone. Use a backend |
Don't pass secrets as deploy-time variables: Groundfloor rejects deploys that send secret-looking names, and copying a stored secret into a deployment with gf deploy --secret is switched off across the platform. Read secrets at runtime with an M2M client that has Read secrets, as above.
Promote between environments
Copy secrets from one environment to another, for example staging to prod, under Build → Environments. The comparison shows which keys differ, never their values. See Environments.
Troubleshooting
| Problem | Likely cause | What to do |
|---|---|---|
| A secret you added isn't there | Another workspace or environment is selected | Check both pickers at the top of the page |
| You can't edit a secret | Groundfloor manages it | Change it where it comes from, such as the managed database |
403 when adding or revealing | Your role can only view secrets | Ask an Admin or Owner to raise your role |
A Coderunner gets 403 reading a secret | Its M2M client can't read secrets | Turn on Read secrets for the client |
Next steps
- Configuration and secrets — read secrets from a Coderunner.
- Secrets API — manage secrets from code.
Environments
Keep dev, staging and prod apart, then compare and promote secrets, flags, apps and Coderunners between them.
Feature flags
Per-environment typed feature flags — manage them in the portal or with gf flags, promote them across environments, and read them at runtime from Shell apps and Coderunners.