License Operations
This page covers running a licensed Enterprise Stack after activation. To activate a license, see Licensing. For the license.conf fields, see License configuration. The quickstart's LICENSING.md walks through offline activation, renewal and disaster recovery with Docker Compose.
What the License Is Bound To
A license is bound to an installation key, not to a host, IP address, database server, connection string or cluster.
- Default: the stack generates the key on first activation. It stores the key and the license credential in its database, encrypted with
LICENSE_STATE_ENCRYPTION_KEY. As long as you keep that data and the encryption key, the license stays valid. - Pinned key: you generate the key yourself, keep it in your secret manager and pass it with
installationKeyFile. The key and a license can then activate an empty database. Configure it before the first activation: if the database already holds a different key, startup fails.
Online and Offline Licenses
| Online | Offline | |
|---|---|---|
| Connectivity | Outbound HTTPS to licenseServerUrl | None |
| Renewal | Automatic, every 12 hours | You export a usage report, walt.id returns a new .waltlicense bundle, and you mount it and restart |
| Credential lifetime | 4 days by default; walt.id can set up to 14 days per license | As agreed, up to one year |
| After expiry | 24 hours of grace, then new operations are blocked | New operations are blocked immediately |
An online stack keeps running through a license-server outage for the rest of its credential lifetime plus the 24 hours of grace. With the default lifetime, that is at least 4.5 days.
What Is Sent to walt.id
- The license contains the license and organization IDs, the type (
devorprod), features, online or offline, usage limits, validity dates and the public installation key. It contains no host, network, database or cluster data. - Usage reports are signed with the installation key. They hold monthly counters per usage type, such as issued credentials, verification sessions, created wallets and key operations. They contain no credential content and no personal data. For each pod they also include the hostname, pod IP, pod and node name, namespace, operating system and version, and stack version.
- Online: the stack sends usage reports automatically every 10 minutes.
- Offline: nothing is sent automatically. A super admin exports the reports with
POST /license/usage-report/exportand sends them to walt.id for renewal. Each report is a signed JWT, so you can decode and review it before sending it. - Offline installation request: only the public installation key, the license and organization IDs, a nonce and timestamps.
Database and Infrastructure Changes
| Change | New license needed? |
|---|---|
| Database version upgrade in place | No. License state is ordinary data in the database. |
| Moving the data to a new database cluster | No. Treat it as a restore. |
| New connection string to the same data | No. |
| Restore from backup | No, if the backup includes all collections and the stack uses the same LICENSE_STATE_ENCRYPTION_KEY. |
| Empty database | Depends on the installation key. See Disaster Recovery. |
| Failover to another site | No. See Failover and DR Drills. |
After a restore:
- An online stack renews its credential on startup. If walt.id is unreachable at that moment, the stack starts only if the restored credential is still within its lifetime plus grace.
- For an offline license, mount the newest
.waltlicensebundle. A bundle with a newer issue date replaces the stored one. - Tell walt.id about the restore. Usage counters go back to the state of the backup.
Disaster Recovery
What you need to recover onto an empty database depends on the installation key:
- Default key: the key is lost with the database. Contact walt.id to release the installation and issue a new license.
- Pinned key, offline license: mount the key and the current
.waltlicensebundle. The stack activates on any empty database without walt.id. - Pinned key, online license: ask walt.id for a new credential offer. The license stays bound to your key, so it does not have to be reissued.
Keep a recovery kit for each environment in your secret manager:
- the pinned installation key
- the current
.waltlicensebundle (offline licenses) LICENSE_STATE_ENCRYPTION_KEY
The step-by-step guide, including a script that generates the key, is Disaster recovery with a pinned installation key.
The Helm chart does not support a pinned installation key yet.
Failover and DR Drills
The license follows the database and the installation key, not the cluster.
- Active/passive with a replicated database and the same
LICENSE_STATE_ENCRYPTION_KEY: nothing to do. - Online licenses: the standby site needs outbound access to
licenseServerUrl. - Pod count: the licensed number of pods applies to the whole deployment. Pods of a failed site keep their slots for up to 3 minutes, so plan headroom for failover and rolling updates.
- Two sites at once: do not run two sites with separate databases on one license at the same time. A second deployment running in parallel needs its own license.
Monitoring
GET /license/statusshows the restriction state, expiry and warnings.- With Prometheus enabled, the stack exports
enterprise_license_seconds_until_expiry,enterprise_license_restriction_stateand, for online licenses,enterprise_license_heartbeat_consecutive_failures.
Alert well before expiry, especially for offline licenses, which have no grace period.
Support
Online renewal is automatic. walt.id handles new licenses, offline renewals and recovery after a lost installation key. Contact us through the Support Portal. Response times follow your support agreement.