Skip to content

Secrets – encrypting passwords and API keys in definitions

Credentials and a few other definitions hold secrets: the password of a mail account, the API key of an AI provider, the access token of an external MCP server. This page describes how nexxcite protects these values, how you switch on their encryption and what changes for administrators who work with them. It is written for the administrators and operators of an installation.

1. Secrets at a glance

Summary

  • Secrets are encrypted before a definition is stored – in the database, in the definition cache and in an exported sketch. You switch the encryption on with a key of your own.
  • A secret is bound to the definition it belongs to. Copied into another definition, it cannot be read there.
  • Secrets are never shown in the code view, whether the encryption is switched on or not.
  • A clone of a definition is created without its secrets. They have to be entered again.

Which values are secrets

Definition Secret
"OpenAI Credentials" The API key
"Anthropic Credentials" The API key
"SMTP Credentials", "IMAP Credentials" The password
"Exchange Online Credentials", "Microsoft Graph API Credentials" The client secret
"LDAP Credentials" The password
"Azure Blob Storage Credentials" The connection string
"S3 Storage Credentials" The access key and the secret key
AI assistant, "External MCP Servers" The access token of each server

In the editors, all of these are password fields: what you type is not shown.

2. Switching the encryption on

  1. Create a key: 32 random bytes, Base64 encoded. On Linux or macOS, for example: openssl rand -base64 32
  2. Set the key and switch the encryption on – preferably as environment variables rather than in appsettings.json:

DefinitionSecrets__Enabled=true DefinitionSecrets__Key=<your key>

  1. Restart nexxcite.
  2. Keep a copy of the key in a safe place, for example your password manager or secret store.

Secrets that are already stored stay readable. They are stored in plaintext until their definition is saved the next time; from then on they are encrypted. To encrypt all of them at once, open each credentials definition and save it.

Without the key, the secrets are lost

A secret that was encrypted can only be read with the key it was encrypted with. If the key is lost, every encrypted password and API key has to be entered again. nexxcite cannot recover them.

If the key is not a valid 32-byte Base64 value, or the encryption is switched on without a key, nexxcite does not start and names the setting in its log.

3. Behaviour in detail

Code view

The code view of an editor ("View Code") shows XXXXXXXXXXXXXX instead of a secret. A secret further down in a definition – the access token of an MCP server – is shown as XXXXXXXXXXXXXX#1, XXXXXXXXXXXXXX#2 and so on.

Changing or deleting these placeholders has no effect: when you switch back to the graphical editor, every secret is what it was before. A token typed into the code view for a newly added MCP server is not taken over. Secrets are changed in the graphical editor only.

Clone

"Clone" in the management view creates the copy without the secrets of the original. nexxcite then tells you which secrets the copy is missing. Open the copy and enter them before it is used – until then, a connection with the copy fails, for example because the mail server rejects the sign-in.

Comparing versions

The stored form of a secret changes only when the secret changes. Saving a definition with another description, for example, leaves its encrypted password exactly as it was, so a comparison of two versions shows a changed secret only where one was entered. The same password in two different definitions is stored differently, so a comparison across definitions does not tell whether they share it.

Replacing the key, or switching the encryption on, changes the stored form of every secret once – the next time its definition is saved.

Sketches

An exported sketch contains the secrets of its definitions encrypted. Imported into an installation with the same key, they work as before. Imported into an installation with another key – for example a production sketch imported into a test system – they cannot be read there. This is intended: credentials of one installation do not belong into another.

A secret that cannot be read

If a secret cannot be decrypted – another key, or a sketch from another installation – nexxcite does not replace it with an empty value. Instead:

  • the password field of the editor says that the value could not be decrypted and has to be entered again,
  • the log names the definition and the secret, once per server start,
  • the encrypted value is kept as it is. If only the key was missing, the secret is readable again as soon as the right key is configured.

A connection that uses such a secret fails until the secret is entered again or the key is configured.

Switching the encryption off

With DefinitionSecrets:Enabled set to false, secrets are stored in plaintext again – each one the next time its definition is saved. Secrets that are still encrypted remain readable as long as DefinitionSecrets:Key stays configured. Do not remove the key before every definition with a secret was saved again.

Replacing the key

  1. Move the current key to DefinitionSecrets:PreviousKeys and set a new one as DefinitionSecrets:Key.
  2. Restart nexxcite. Secrets of the old key stay readable; every definition is encrypted with the new key the next time it is saved.
  3. Remove the old key from PreviousKeys only once every definition with a secret was saved again.

4. Several servers

All servers of an installation have to be given the same key (and the same previous keys). A server with another key cannot read what the others stored. See Running several servers.

5. Settings for operation

These settings belong to the section DefinitionSecrets. Which values count as secrets cannot be configured.

Setting Default Meaning
DefinitionSecrets:Enabled false Encrypts secrets when a definition is stored.
DefinitionSecrets:Key empty The key: 32 random bytes, Base64 encoded. Required when the encryption is switched on, and as long as encrypted secrets exist.
DefinitionSecrets:PreviousKeys empty Keys used before the current one. Only used to read secrets they encrypted.

6. Limitations

  • Secrets that were stored before the encryption was switched on are encrypted only when their definition is saved again. There is no function that encrypts all of them at once.
  • The key is not replaced automatically. Replacing it is the procedure in section 3.
  • The encryption protects the stored values. Administrators who may edit a credentials definition can still enter a new secret, and nexxcite uses the secrets in plaintext when it connects to the service.

7. Frequently asked questions

Does the encryption change anything for existing credentials? No. They keep working. Their secrets are encrypted the next time they are saved.

Can I see a stored password in the code view? No. The code view never shows a secret, whether the encryption is switched on or not.

Why is a cloned credentials definition not working? A clone does not carry the secrets of the original. Open the copy and enter them again.

We imported a sketch, and a password field says the value could not be decrypted. Why? The sketch was exported from an installation with another key. Enter the secret again, or configure the key of that installation in DefinitionSecrets:PreviousKeys.

Can I use the same key in a test and a production installation? Yes, but then a sketch from production brings working production credentials into the test system. Using a separate key per installation prevents that.