#Licensing

The walt.id Enterprise Stack is licensed software. A license from walt.id is required to run it.

This page shows you how to get a license, configure activation, start the stack, and stay in good standing. Field-level reference for license.conf is in License configuration.

#Getting a License

If you are not a customer yet, contact walt.id.

Once you are a customer, walt.id provides:

• Access to the private Enterprise Stack images
• A license for each environment you run

Licenses are issued as development or production:

• Development — local setup, evaluation, and non-production environments. Requires dev-mode in _features.conf.
• Production — live deployments. dev-mode must be disabled.

Your agreement also determines which capabilities are included. Features outside your license are not available, even if they are enabled in _features.conf.

walt.id issues the license as one of:

• An online OpenID credential offer (openid-credential-offer://...) for connected environments
• An offline .waltlicense bundle plus a matching installation key for air-gapped environments
• A raw signed license credential (SD-JWT VC) for controlled migration or recovery

#Prerequisites

Before you activate, ensure you have:

• A license from walt.id for this environment
• MongoDB available to the Enterprise API (license state is stored there)
• config/license.conf mounted with the rest of the configuration files
• LICENSE_STATE_ENCRYPTION_KEY set on every replica (at least 32 characters)
• For online licenses: outbound access from the Enterprise API to walt.id's license service (licenseServerUrl, typically https://license.walt.id)
• For development licenses: dev-mode enabled in _features.conf
• For production licenses: dev-mode not enabled

#Activate the License

Put license.conf in the API config directory (the enterprise quickstart already includes this file). Set licenseServerUrl to the URL walt.id gives you, then use exactly one seed option.

licenseServerUrl = "https://license.walt.id"
seedCredential = "openid-credential-offer://..."

#Docker Compose (quickstart)

1. Edit config/license.conf with the seed option above.
2. Pass the encryption key into the API service:

waltid-enterprise:
  environment:
    - LICENSE_STATE_ENCRYPTION_KEY={your-32-plus-character-secret}

3. Start the stack as in Local Development.

#Docker

docker run -p 3000:3000 \
  -v $(pwd)/config:/config \
  -e LICENSE_STATE_ENCRYPTION_KEY="{your-32-plus-character-secret}" \
  waltid/waltid-enterprise-api

#Kubernetes

Mount license.conf with the other config files. Store the encryption key (and optionally the online offer) in a Secret named waltid-enterprise-license. See License configuration and Kubernetes Deployment.

#Confirm Activation

After the API is up, sign in as a super admin and call the license status endpoint.

curl -X 'GET' \
  'http://enterprise.localhost:3000/license/status' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer {yourToken}'

{
  "restriction": "ACTIVE",
  "licenseId": "lic_abc123",
  "organizationId": "org_abc123",
  "licenseType": "prod",
  "offline": false,
  "features": ["*"],
  "usageLimits": {},
  "rateLimitPerHour": null,
  "disabledFeatures": [],
  "haltOnStartup": false,
  "expiresAt": 1893456000,
  "expiresInSeconds": 7776000,
  "expiringSoon": false,
  "warningMessage": null
}

🎉 You've activated the Enterprise Stack license when restriction is ACTIVE.

Related super-admin endpoints:

#After Activation

The stack stores the bound credential and installation key in MongoDB, encrypted with LICENSE_STATE_ENCRYPTION_KEY.

• Later restarts reuse that persisted state. You do not redeem the online offer again.
• All replicas of one deployment must share the same MongoDB and the same encryption key.
• Do not scale the replica count above the licensed fleet size. Extra pods stay alive for /livez and license status, but other routes return 503.
• A newer mounted offline .waltlicense bundle (later issuedAt) is treated as an explicit renewal.

#Staying Licensed

Connected deployments periodically check in with walt.id. That check confirms the license is still valid, reports usage against your agreement, and lets walt.id disable a license or individual features if the contract requires it.

Allow outbound access from the Enterprise API to licenseServerUrl.

If the stack cannot reach walt.id for a short time, it keeps running while the cached credential is still valid or within grace (currently 24 hours after expiry for online licenses). After a longer outage, new operations are blocked until connectivity is restored or the license is renewed. Work already in progress is allowed to finish.

walt.id can also remotely restrict a license. When that happens, the API returns 503 with Enterprise API is unavailable because the license is not active. except for:

• GET /livez
• Login and logout
• GET /license/status
• POST /license/usage-report/export

#Offline and Air-Gapped Environments

If your environment cannot reach walt.id, an offline license can be issued instead.

• The stack does not need ongoing connectivity to stay licensed
• Usage is still recorded locally
• You send a signed usage report to walt.id on the schedule they give you (POST /license/usage-report/export)
• As usage approaches the contractual limits in the license, the stack tightens automatically (rate limits, then some features, then a block on new billable operations)

If an offline license expires or its usage allowance is exhausted, new operations are blocked until walt.id issues a renewal. Mount the new bundle and restart (or roll) the API so the newer issuedAt is picked up.

#Troubleshooting

If the stack reports that it is unlicensed or restricted and the table above does not resolve it, contact walt.id.

#What You Should Do

1. Get a license from walt.id (contact us).
2. Configure license.conf and LICENSE_STATE_ENCRYPTION_KEY for each deployment.
3. Start the API and confirm GET /license/status returns ACTIVE.
4. For connected deployments, allow outbound access to walt.id's license service.
5. For air-gapped deployments, export usage reports on the schedule walt.id gives you.

#Next Steps

• License configuration — license.conf fields and the encryption key
• Local Development — run the stack locally
• Kubernetes Deployment — production-style deploy
• Features — _features.conf and dev-mode