Skip to content
Plugboard docs

Secrets and keys

These keys serve different purposes and have different recovery requirements.

Key Protects If lost
SECRETS_MASTER_KEY or configured master keyring Connector credentials and encrypted .pbk archives Archives cannot be decrypted; credentials restored from SQL need reconfiguration
JWT_SECRET Signed access and portal sessions Existing signatures become invalid; rotate/revoke refresh sessions separately
LICENSE_PUBLIC_KEY Verifying licences Get it again from us. It is public

SECRETS_MASTER_KEY

Section titled “SECRETS_MASTER_KEY”

This is the key to be careful about. Connector credentials are encrypted with it before they reach the database and decrypted in memory only for the duration of a call. Backups are encrypted with it too.

What losing it looks like

Section titled “What losing it looks like”

An encrypted .pbk archive cannot be opened or restored without its matching key. A separate SQL dump or portable JSON export can restore database records, but connector credentials inside those records remain encrypted. Recovering their use then requires the original key or reconfiguring each integration with its original credentials.

The current vault implementation uses AES-256-GCM with an environment-backed key provider. SECRETS_MASTER_KEYS supplies a map of key IDs and SECRETS_ACTIVE_KID selects the active key. Retain older key IDs while archives or stored credentials still depend on them. There is no implemented KMS or Vault key-provider adapter in this release.

Where the copy goes

Section titled “Where the copy goes”

A password manager, somewhere the server cannot reach. If the server and everything it can reach disappeared tonight, you should still have the key.

Generating one

Section titled “Generating one”
Terminal window
openssl rand -base64 32

Generate a fresh one for each deployment. Do not copy one from another install, from documentation or from a demo.

Rotating it

Section titled “Rotating it”

Rotating the key re-encrypts everything the vault holds, so treat it as a planned change. Take a backup first, and afterwards confirm a connector still tests successfully.

JWT_SECRET

Section titled “JWT_SECRET”

Signs access tokens and underpins portal-session signatures. Staff refresh tokens are separate random credentials stored as hashes. Changing JWT_SECRET invalidates old signatures but is not a substitute for revoking refresh sessions after a compromise.

Terminal window
openssl rand -base64 48

Licence keys

Section titled “Licence keys”

Your instance verifies its licence locally with a public key, so:

  • Nothing calls home at sign-in.
  • A network outage cannot disable your service desk.
  • We cannot change what you are entitled to without issuing a new licence.

LICENSE_PUBLIC_KEY is the same value for every customer and is not a secret.

Key rotation is supported through a keyed map, and specific licences can be refused locally:

Terminal window
LICENSE_PUBLIC_KEYS='{"k_ab12cd34":"LS0tLS1CRUdJTiBQVUJM..."}'
LICENSE_REVOKED_JTIS="..."

Connector credentials

Section titled “Connector credentials”

Stored encrypted, never displayed again after saving, and never written to the audit log. Configuring a connector is logged; the token you pasted is not.

Leaving a secret field blank when re-saving keeps the existing value, so you can change a base URL without re-entering a token you no longer have a copy of.

Connector agent tokens

Section titled “Connector agent tokens”

A connector agent enrolment token is a credential into your network. It is shown once, only its hash is stored, and revoking it takes effect on the next poll.

API keys

Section titled “API keys”

API keys are shown once and stored as hashes. A lost key is reissued rather than recovered.

The environment file

Section titled “The environment file”

.env holds all of the above on a self-hosted install. Treat the file accordingly:

Terminal window
chmod 600 .env

An install-folder copy containing .env includes sensitive credentials. It is not necessarily a complete backup: Docker volumes, external storage and custom backup directories need to be included separately.

What we hold on managed hosting

Section titled “What we hold on managed hosting”

We hold per-deployment secrets in escrow, which is what lets us restore your deployment, and it is why a key handover is part of moving to self-hosting.

We do not hold your connector credentials in the clear. Those are encrypted with your deployment’s key, the same as anywhere else.

Section titled “Related”