Websites
Storing App Secrets For a Site
The Secrets tab is an encrypted store for the sensitive configuration values a Node.js app needs, such as API keys, signing secrets and third-party tokens, kept per environment so your production credentials and your preview credentials never get mixed up.
Where Secrets Live
Open Websites, click the site, open the Advanced menu in the site tab strip, and choose Secrets. The tab is titled Secrets.
The tab only appears on Node.js sites. WordPress, PHP and static sites do not show it, because their configuration lives in files on disk instead: wp-config.php for WordPress, and whatever your framework reads for a plain PHP app.
How Values Are Protected
Every value is encrypted before it touches the database. Nothing is stored as readable text, and the list view never shows a full value: it shows a mask with only the last four characters, so you can tell two similar keys apart without exposing either.
Each row carries an Encrypted pill as a reminder of that. Reading a value back is a separate, deliberate action rather than something that happens just by opening the page.
Setting, revealing and deleting a secret all require the sites:write permission. A read-only team member can see which keys exist and their masks, but not their values.
The Two Environments
A segmented control at the top of the page switches between production and preview. They are completely separate sets of keys. Setting STRIPE_SECRET_KEY in production does not create it in preview, and deleting it from preview does not touch production.
That separation is the point of the feature. Preview builds are throwaway environments that anyone with repository access can trigger, so they should carry test credentials, not live ones. See Preview Deploys For Pull Requests for how preview environments are created.
Adding or Updating a Secret
- Choose the environment with the segmented control.
- Type the name in the KEY_NAME field. The field forces upper case as you type.
- Put the value in the second field. It is masked as you type.
- Click Set.
Setting a key that already exists overwrites it. There is no separate edit action and no confirmation step for an overwrite, so check the environment tab before you click Set.
Key Name Rules
A key must start with a capital letter and may then contain capital letters, digits and underscores, up to 128 characters. DATABASE_URL, API_KEY_V2 and SENTRY_DSN are all valid. Anything else is rejected with the message Key must be UPPER_SNAKE_CASE letters/numbers/underscore.
Two other limits are worth knowing:
- A value cannot be empty. Submitting a blank value returns value required.
- A value cannot exceed 16 KB. That is generous for a token but not enough for, say, a full certificate chain, which belongs in a file rather than a secret.
Reading a Value Back
Click Copy on the row. KPanel decrypts the value server-side and puts it straight on your clipboard, with a Value copied to clipboard confirmation. The value is not printed on screen, so a screen share or a shoulder-surfer does not pick it up.
Every reveal is written to the site's audit trail, along with who did it and which key, and shows up in the Site Activity Log.
If you need to check that a value is correct without exposing it, compare the mask instead. The last four characters are enough to confirm you have the right token, and they are already on screen.
Using a Secret In Your App
Copy the value into wherever your application reads its configuration on the server. For a Node.js app that is normally an environment variable set by your process manager, or an .env file in the app root that your code loads at start-up.
Do not commit that file to your repository. Add .env to .gitignore before you create it. A secret that has been pushed to a git remote has to be treated as leaked and rotated at the provider, because it stays in the history even after you delete the file.
The Secrets tab is your record of what the value is, held encrypted and audited, rather than a note in a password manager or a message thread. Keep it as the source of truth: when you rotate a key at the provider, update it here at the same time, so the next person to deploy has the current value.
Deleting a Secret
Click Delete on the row. KPanel asks you to confirm with Delete {KEY}? and warns that the app will lose access to this value at its next restart. There is no undo and no copy kept, so if you might need the value again, copy it first.
Delete a secret when the underlying credential has been revoked at the provider, or when the code that used it has been removed. Leaving stale keys around makes it harder to tell, later, which ones actually matter.
Rotating a Credential Safely
The safe order is always: create the new credential at the provider, update it here, deploy, confirm the app works, then revoke the old credential at the provider.
Doing it the other way round, revoking first, gives you a window where the running app is holding a dead credential and every request that needs it fails. If the change is risky, take a backup first so you can get back to a known-good state: see Taking a Backup.
Troubleshooting
The Secrets tab is not in the menu. The site is not a Node.js site. Check the stack pill next to the site name at the top of the page.
The Set button does nothing. Both fields are required. The button reports Key + value required if either is empty.
The key was rejected. Lower case letters, hyphens, dots and spaces are not allowed. api-key and Api_Key both fail; API_KEY passes.
Copy did not put anything on the clipboard. Some browsers block clipboard writes on an inactive tab. Click on the page first, then click Copy again.
Where To Go Next
- Preview Deploys For Pull Requests, the other half of the production and preview split.
- Git Deploy For a Site for pushing the code that reads these values.
- Site Activity Log to see who set, revealed or deleted a secret.