The encryption key, explained simply

What this is: a single secret password that belongs to your TSync installation and nobody else's. TSync uses it to lock away the sensitive credentials it stores for you.

Why you care: it's like the master key to a safe inside your system. As long as you keep that key, TSync can open the safe and use the things inside. If you ever swap the key, the safe stays shut forever — and what's inside is gone. So the golden rule is short: set it once, keep a copy, never change it.

What it actually protects

The key scrambles the connection details and credentials TSync needs to talk to other services, such as:

  • passwords for sending and receiving email (SMTP / IMAP)
  • payment connections (like Stripe) and their keys
  • sign-in links to Google or Microsoft
  • other third-party logins TSync stores on your behalf

One thing it does NOT touch: the passwords your staff and customers use to log in. Those are protected separately, with a one-way method that even TSync can't reverse — which is exactly what you want for login passwords. You don't have to do anything for that to work.

Where it lives

The key sits in one configuration file, application/config/app-config.php, on a line that looks like this:

define('APP_ENC_KEY', 'a8K3jD9mP2xQ7vR4nL5wT8sF1bC6yU9z');

That long jumble of letters and numbers is the key itself.

Three rules worth remembering

1. It must be exactly 32 characters long

Not 31, not 33 — exactly 32. If it's the wrong length, TSync won't start and will tell you:

Encryption key length should be 32 characters

If you ever see that message, the fix is simply getting the key back to 32 characters.

2. Stick to plain letters, numbers and simple symbols

Upper- and lower-case letters and digits are perfect. Avoid anything exotic — no line breaks, tabs, or unusual symbols — so the key stays readable everywhere.

3. Never change it after installation — this is the big one

This is the rule that really matters. Everything TSync locked away with the original key can only be unlocked with that same key. Change the key and all of it becomes unreadable — you'd lose your saved email passwords, payment keys, and Google/Microsoft connections in one go.

Don't worry — this only happens if the key is deliberately changed. Normal use, updates, and backups never alter it.

If the key ever leaks (for example, it accidentally ends up in a public code repository), then — and only then — you'd want to replace it, knowing it means starting fresh:

  1. Generate a new key.
  2. Re-enter every integration's credentials by hand (email passwords, payment keys, etc.).
  3. Have anyone using Google/Microsoft sign-in reconnect their account.

Creating a key (only when first installing)

The easy way: let the installer do it

When you install TSync and finish the database step, the installer creates a strong random key for you automatically. You don't have to lift a finger — just glance at app-config.php afterward and confirm there's a value on the APP_ENC_KEY line.

Doing it by hand (if you ever need to)

On Linux or macOS, this command prints a fresh 32-character key:

LC_ALL=C tr -dc 'A-Za-z0-9' < /dev/urandom | head -c 32

Or, using PHP, this prints one too:

php -r "echo bin2hex(random_bytes(16));"

(There are websites that generate keys, but only ever use those for testing — never for a real, live system.)

Keep a safe copy — this is the part people forget

Please save this key somewhere safe today. The best home for it is a password manager (such as 1Password or Bitwarden). Here's the scenario to avoid: you have a perfect database backup, you lose the server, you restore the database onto a new one — but without the original key, none of the locked-away credentials can be read again. The backup alone isn't enough; the key is the other half.

A complete backup really means three things together:

  1. The database backup
  2. A copy of application/config/app-config.php (this file holds the key)
  3. A copy of your uploads/ folder (logos, attachments)

How to look up your current key

To simply see the key on its line:

grep "APP_ENC_KEY" application/config/app-config.php

To confirm it's the right length (it should print 32):

php -r "include 'application/config/app-config.php'; echo strlen(APP_ENC_KEY) . PHP_EOL;"

What happens if the key stops working

From v11.1.1 the answer is short: the system refuses to save, and tells you why.

This matters most for national identification numbers (CNP / IDNP) on an employee record. They are special-category personal data, so they are only ever stored encrypted.

If the key is missing or unusable and you try to save an employee with a CNP or IDNP typed in:

  • the employee is not saved at all — not even partially;
  • you get a message saying so, and what to check;
  • everything else you typed stays on the form.

Saving an employee without an identifier still works normally. The refusal only covers the data it protects.

Why refuse instead of saving what it can? Before v11.1.1 the identifier was silently replaced with a placeholder while the last four digits stayed visible — so the record looked complete and the number was gone. Nobody found out until somebody needed it. An employee you have to save twice is an inconvenience; a personal identification number that quietly disappeared is not recoverable.

Already have records like that? The Health page (Setup → Health) reports them in two separate groups, because they are not the same problem:

  • stored readable — the number is still there but unprotected. It can be repaired: open the employee and re-enter it, and it will be stored encrypted.
  • lost — only the last four digits remain. No repair can bring these back; somebody has to ask the employee and type the number again.

See also