Secrets and keys
| 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”openssl rand -base64 32Generate 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.
openssl rand -base64 48Licence 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:
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:
chmod 600 .envAn 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”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.
Related
Section titled “Related”- Backups and restore, where this matters most.
- The security model.
- Compliance answers.