Configure the Credential Store

Configure the runtime master key so sensitive drivers and workflows can store and retrieve encrypted credentials.

Prerequisites

Access to configure the environment of the Orchestrator application process and restart or recreate it.
A secure location for the master keys, held separately from database backups.
A SENSE System Admin account (SYSTEM_ADMIN) to verify readiness in the portal.

For an existing database, recover the keys that encrypted its credential rows before changing configuration. Never overwrite an existing key with a new value under the same version. Use the master-key rotation procedure when changing keys for a populated store.

Procedure

Establish the Configuration

Choose exactly one current-key source: SENSE_CRED_KEY or SENSE_CRED_KEY_FILE. Prefer a read-only mounted secret file.
If older live credential rows require previous keys, set the previous-key sources and configure those versions. Retain historical keys needed only by database backups separately in secure custody.
Configure the selected variables in the application runtime using the reference below:

Variable	Value and behavior
`SENSE_CRED_KEY`	Current key as `<version>:<base64-key>`. A bare `<base64-key>` means version 1. Mutually exclusive with `SENSE_CRED_KEY_FILE`.
`SENSE_CRED_KEY_FILE`	Path to a readable file containing the current-key value. The path is resolved in the application process’s filesystem. Mutually exclusive with `SENSE_CRED_KEY`.
`SENSE_CRED_KEY_PREVIOUS`	Previous keys as `<version>:<base64-key>` entries separated by commas or newlines. Every entry requires a version. Mutually exclusive with `SENSE_CRED_KEY_PREVIOUS_FILE`.
`SENSE_CRED_KEY_PREVIOUS_FILE`	Path to a readable file containing the previous-key list. Mutually exclusive with `SENSE_CRED_KEY_PREVIOUS`.
`SENSE_CRED_REVEAL_DISABLED`	Development safeguard: `true` disables plaintext reveal for everyone without blocking internal consumption. Unset, blank, or `false` leaves owner reveal enabled. Values are trimmed and case-insensitive; any other value disables reveal and produces a warning.

A version is a simple positive integer. The key must be standard base64 encoding of exactly 32 decoded bytes. Leading and trailing whitespace around a current-key value or previous-key entry is stripped; do not insert whitespace inside the version or encoded key. An example key could therefore be something like 4:kP/eywstRgCW3RSjzG9NTu5cphUyzn115qGY2K7YMck=.

Duplicate previous versions, including a version equal to the current version, are reported as DUPLICATE and are not loaded. Entries with an invalid version or key are reported as INVALID and are also not loaded.

An ambiguous or unreadable previous-key source only produces a warning; it does not by itself disable a valid current key. Those warnings still require attention when existing rows depend on the missing keys.

Provision and Apply the Key

For a new store, generate a random 256-bit key:
Terminal window
```
openssl rand -base64 32
```
Handle the output as a secret. Store it in the selected runtime secret source, using a version prefix such as 1:<base64-key>. Retain the key securely for recovery.
Supply the selected variables to the Orchestrator application process. For file inputs, also provide the file and ensure the application can read it. Setting a file variable does not create a container mount.
Apply the deployment-specific configuration and start a fresh application process. Keys and reveal policy are read at startup, so changing any keys requires a restart.

The runtime reads these values from environment variables, not system.properties or the frontend .env file. Keep key material out of source control, application images, and deployable EAR files.

Verify

Sign in with SYSTEM_ADMIN and open Admin Settings → Credentials.
Confirm Store Active and the expected Key Version.
Confirm every required previous key is LOADED. Resolve Previous Key Unavailable, Previous Keys Unavailable, stranded versions, and undecryptable-row warnings before using dependent workflows.
Confirm there is no Key verification incomplete warning. Completed verification alone does not prove every row decrypts; assess the row and key warnings as well.

An empty, correctly configured store can show No Credentials Present alongside Store Active. Configure a participating workflow only after readiness checks pass; application health alone does not verify credential recovery.

Troubleshooting

For Store Unavailable, first check the selected current source, version syntax, and runtime file permissions. A whitespace-only environment variable is treated as absent; a readable current-key file containing only whitespace is invalid. Restart or recreate the application after correcting the runtime configuration.

For mismatches or undecryptable rows, restore matching keys rather than overwriting an existing version. For Key verification incomplete, check database connectivity before rotating keys. See the Credential Store readiness diagnostics for exact failure reasons and previous-key warnings.