Managing Secrets

Secrets hold sensitive values — API keys, passwords, tokens — that the platform stores encrypted and injects into your apps by reference. Their values are write-only: after you save a secret, nobody can read the value back through the dashboard or the API. You can only replace it.

Every secret has three parts:

• Name — uppercase letters, numbers, and underscores, starting with a letter and not ending with an underscore (e.g. STRIPE_API_KEY). The dashboard normalizes what you type. Names are at most 253 characters. Names ending in _S3, _REDIS_CONN, _MONGODB_PASSWORD or _MARIADB_PASSWORD are reserved for the credentials the platform creates for your buckets and databases. The name is what apps reference; it need not match the app variable key.
• Value — entered once, then hidden.
• Description — optional, shown in the secrets list so teammates know what the value is for.

Creating, editing, and deleting Project and Environment secrets requires the manage-secrets capability on the project (see Access Control). Organization secrets can only be managed by the Organization’s Owner and Admins. Secrets are managed in the dashboard; the CLI links apps to them but does not create them.

Choosing a scope

Secrets live at one of three levels:

• Organization — shared across the whole Organization.
• Project — shared by all of a Project’s Environments.
• Environment — specific to one Environment. This is the most common scope: production credentials that staging must never see.

Pick the narrowest scope that works. A production database password belongs on the production Environment, not on the Organization.

Creating a secret

Each scope has its own secrets page in the dashboard:

• Environment — open the Environment’s Secrets page and click Add Secret.
• Project — open the Project’s settings and go to the Secrets tab (Project Secrets).
• Organization — open the Organization’s settings and find Organization Secrets.

In each case, enter a name, the value, and an optional description. The value field is masked as you type; each form has a Show toggle if you need to double-check it before saving.

Editing a secret

Environment secrets have an Edit action in the list; because values are write-only, its value field starts empty — enter a complete new value (there is no way to view or append to the old one), or leave it blank to keep the current value and change only the description, and save. Project and Organization secrets have no Edit action in the dashboard yet. To change one, send the new value to the API with PUT /api/v1/organizations/<org>/projects/<project>/secrets/<name> (Project) or PUT /api/v1/organizations/<org>/secrets/<name> (Organization) and a body of {"value": "<new value>"}; see API Access & Automation. The CLI can’t change secrets. In every scope, the name is fixed: to rename a secret, create a new one, move the links to it, then delete the old one.

This is also how you rotate a credential: edit the secret with the new value. The new value reaches your Environments within seconds, and every app that links to the secret restarts on its own to pick it up — a rolling restart, so a multi-instance app keeps serving traffic (a singleton app is stopped and started again, so it is briefly unavailable).

Deleting a secret

Click Delete on the secret and confirm. Deletion is permanent and cannot be undone. An Environment or Project secret that an app still links to can’t be deleted — remove those links first. An Organization secret can be deleted while apps link to it, and those links then lose their source, so update or remove them first.

Binding a secret to an app

A secret does nothing on its own — an app picks it up through an environment variable that references the secret instead of holding a literal value.

In the dashboard, open the app’s Environment Variables section, add a variable, and choose Link to secret, picking the secret from the list. The list shows the Environment’s secrets, then the Project’s, then the Organization’s. Organization secrets appear only for the Organization’s Owner and Admins. A name that a nearer scope also has appears once, in the nearer scope.

With the CLI, use paas config set --secret-ref with the secret’s name followed by the variable key to create on the app:

paas config set --secret-ref STRIPE_API_KEY STRIPE_API_KEY \
  -o acme -p shop -e production -a web

The variable key doesn’t have to match the secret’s name — you can point PAYMENT_KEY at STRIPE_API_KEY. Both start with an uppercase letter. The secret must already exist in the Environment, the Project or the Organization. Only the Organization’s Owner and Admins can link an Organization secret. See secret resolution. Your app reads the result as an ordinary environment variable.

See Environment Variables for the full guide to per-app configuration.

When changes reach your app

Secret values are read when an instance starts. Use this lifecycle table to decide whether a manual restart is necessary:

For that last case:

paas restart -o acme -p shop -e production -a web

To rotate a Project or Organization secret, change its value as described in Editing a secret rather than deleting and re-creating it. See Restarting an App and startup validation.

Next steps

• Environment Variables — plain values, hidden values, and secret links on an app
• Secrets & Configuration — how configuration flows through the platform
• Restarting an App — picking up rotated values
• Access Control — who can manage secrets