Skip to content
plugboard.appRequest a demo

Security and privacy

Secrets and keys

KeyProtectsIf lost
SECRETS_MASTER_KEY or configured master keyringConnector credentials and encrypted .pbk archivesArchives cannot be decrypted; credentials restored from SQL need reconfiguration
JWT_SECRETSigned access and portal sessionsExisting signatures become invalid; rotate/revoke refresh sessions separately
LICENSE_PUBLIC_KEYVerifying licencesGet it again from us. It is public

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.

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.

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

Terminal
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 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.

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
openssl rand -base64 48

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
LICENSE_PUBLIC_KEYS='{"k_ab12cd34":"LS0tLS1CRUdJTiBQVUJM..."}'
LICENSE_REVOKED_JTIS="..."

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.

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 are shown once and stored as hashes. A lost key is reissued rather than recovered.

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

Terminal
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.

Connector credentials are encrypted with your deployment’s SECRETS_MASTER_KEY, the same as anywhere else, and never stored in the clear. Where copies of that key live decides who could open them.

On the server we run for you. The key is in the deployment’s configuration on its server, because the deployment needs it to open your connector credentials for each call. We operate that server, so we are able to decrypt your connector credentials there. What prevents it is our administrative access control, not the encryption.

In our control plane, while your server is built. The control plane generates your deployment’s configuration and holds all of it, sealed, until the deployment goes live, because the build needs it. At go-live it:

  • encrypts the master key to an offline escrow key that the control plane cannot open, and stores only that ciphertext
  • cuts its own copy down to the support key, the licence key and settings that are not secret, such as the address, region and school name
  • records that it has done so

From then on the control plane holds nothing that opens your connector credentials or your backups. The support key it keeps opens nothing until you grant support access.

In escrow. The private half of the escrow key is held offline, never on a server. It is used only to rebuild a deployment whose server and the hosting provider’s backups of that server are both lost, so that its offsite backups can be restored, or to hand a school its key when it moves to self-hosting. During a rebuild the key passes through the control plane again, sealed, until the rebuilt deployment goes live.

Handing a school its key. The request comes in writing from the principal or business manager, sent from the school’s domain, and we confirm it by calling the school’s published number, which we look up rather than take from the request. We then send the whole key ring by hand, in a file encrypted with a passphrase, with the passphrase spoken on that call: never through a server or the support ticket, or in plain email. The school rotates its key once its own server has restored its backups, so the escrowed ring opens nothing it seals afterwards. See moving between hosting models.

Self-hosted deployments set up through onboarding receive a configuration we generated, including SECRETS_MASTER_KEY. The control plane cuts its copy down in the same step that records the bundle as downloaded, and escrows nothing, so from then on the key is yours alone. Generate a new key and rotate to it if you want one we never generated.