Licensing

Cirata Symphony uses a pool-based licensing model. Vendor-issued license files grant a pool of units that are consumed as extensions report usage. Each license is cryptographically signed using Ed25519 to prevent tampering.

How Licensing Works

1. Vendor issues a license—a JSON file containing a unit pool, expiry date, grace period, and conversion rates for each extension's dimensions.
2. Administrator uploads the license—via the Licensing > Licenses tab in the Symphony UI.
3. Extensions report usage—as extensions operate, they report usage in their own dimensions (e.g., tables replicated, bytes transferred).
4. Dimensions are converted to units—Symphony converts raw dimensions to units using the rates embedded in the license.
5. Usage is auto-attributed—if attribution rules are configured, matching records are automatically assigned to a business unit for attribution and cost allocation.
6. Enforcement triggers when units are exhausted—once the pool is depleted, a grace period begins, after which extensions may be disabled.

License Lifecycle

Each license moves through the following states:

Status	Description
Active	The license is valid, not expired, and has remaining units.
Grace Period	Licensed units are exhausted but the grace period has not yet expired. Extensions continue to operate.
Expired	The license has passed its expiry date, or the grace period has elapsed after unit exhaustion. A license that has expired by date but is still within its grace period is shown as Expired in the license list, though its covered extensions continue to operate during the grace window.
Revoked	The license was manually revoked by an administrator.

The status is computed automatically based on dates and usage—you do not set it directly.

Deployment-Locked Licenses

Each Symphony deployment has a unique deployment key derived from its operator keypair. Licenses must include this key so that a license issued for one deployment cannot be used in another.

Obtaining Your Deployment Key

1. Navigate to Licensing > Licenses.
2. Click Add License.
3. Your deployment key is displayed at the top of the upload drawer with a copy button.
4. Provide this key to your vendor when requesting a license.

The vendor includes your deployment key in the license file as the deployment_key field. Because it is covered by the license's cryptographic signature, it cannot be altered after signing.

Why Deployment Locking?

Deployment locking ensures that:

• A license issued for a production deployment cannot be reused in a test environment (or vice versa).
• The vendor can be certain that a license is only active in the intended deployment.
• If a deployment is re-provisioned with a new operator keypair, a new license must be issued.

Uploading a License

1. Navigate to Licensing > Licenses.
2. Click Add License.
3. Either paste the vendor-issued license JSON into the text field, or click Select License File to upload a .json file.
4. Click Upload.

Symphony verifies the Ed25519 signature and checks that the deployment_key in the license matches this deployment's operator public key before accepting the license. If the signature is invalid, the deployment key does not match, or the JSON is malformed, the upload is rejected with an error message.

info

You can upload multiple licenses. Symphony uses a first-expiring-first strategy: for each usage report, only licenses that define a unit rate for the reporting extension are considered. Among those, usage is charged to the soonest-expiring license that still has remaining capacity, then overflows to the next. When two licenses share the same expiry date, the earlier-issued license is consumed first. Unit pools from all active and grace-period licenses are summed to determine total available capacity.

Understanding Unit Rates

Each license includes unit rates that define how extension-specific dimensions are converted into units. For example:

{
  "unit_rates": {
    "iceflow": {
      "extension": "iceflow",
      "description": "Ice Flow",
      "dimensions": {
        "tables_replicated": 0.5,
        "gb_transferred": 0.01
      }
    }
  }
}

In this example, each table replicated by the iceflow extension consumes 0.5 units, and each GB transferred consumes 0.01 units.

Unit rates are set by the vendor at license issuance and cannot be modified by the customer. The dimensions used in a license need to match how an extension reports usage, and will be named as required by each extension.

Grace Periods

A grace period begins when licensed units are exhausted or when a license passes its expiry date, provided the license has a non-zero grace_period_days value:

• Unit exhaustion—when the total unit pool is depleted, the grace window is measured from when units were first exhausted.
• Date expiry—when a license passes its expires_at date, the grace window extends for grace_period_days beyond that date.
• If both conditions apply (units exhausted and date expired), Symphony uses whichever grace window extends furthest into the future.

During the grace period:

• Extensions covered by the grace-period license continue to operate, but show a Warning status in the UI.
• Extensions covered by other fully active licenses are unaffected and show their normal Operating status.
• The enforcement state is published to the symphony_enforcement KV bucket for extensions to observe.
• If the grace period expires without a new license being uploaded, enforcement is applied and affected extensions show Unlicensed.
• When multiple licenses exist, each license's grace period is evaluated independently. The overall enforcement state remains in a warning state as long as any license still has an active grace period; the reported grace expiry is the latest across all licenses.

Grace periods are not configurable by the administrator—they are part of the vendor-issued license.

Enforcement States

Symphony continuously monitors usage against the license pool and publishes the enforcement state:

State	Condition	Effect
OK	Usage below 90% of licensed units	Normal operation
Warning	Usage at or above 90% of licensed units, or a license has expired and is within its grace period	Warning displayed; extensions operate normally
Unlicensed	Grace period expired or no valid license	Extensions may be disabled

The enforcement state is published to the symphony_enforcement KV bucket (key: state) so extensions can watch for changes reactively. The state includes status, remaining_units, message, timestamp, grace_expires_at (if in grace), disabled_extensions (individually disabled extensions), and grace_extensions (extensions covered only by grace-period licenses). Extensions can use the SDK's enforcement state methods to read the current state or watch for updates.

Per-Extension Enforcement

Enforcement indicators are applied per-extension based on each extension's license coverage:

• Green (Operating)—The extension is covered by at least one fully active license.
• Amber (Warning)—The extension is covered only by grace-period licenses (no fully active license covers it). It continues to operate but should be addressed before the grace period expires.
• Red (Unlicensed)—The extension reports dimensions that are not covered by any active or grace-period license, or all grace periods have expired.

An extension that is covered by both a grace-period license and a fully active license shows as Operating, not Warning—only extensions whose sole coverage comes from grace-period licenses are affected.

The Status card on the Usage tab shows the overall enforcement state with per-extension colored dots reflecting these individual statuses.

warning

Ensure that every extension's reported dimensions match the dimension names defined in the license's unit rates. Uncovered extensions will be individually disabled even if the overall license pool has remaining capacity.

Ongoing Validation

Symphony continuously validates all stored licenses—not just at upload time. Each license must pass both signature verification (Ed25519) and deployment key verification (matching the current operator public key) to be considered active. Licenses that fail either check are automatically excluded from:

• The licensed unit pool and enforcement calculations
• Usage chart capacity lines and remaining-units computation
• The summary cards on the Usage tab (Available Units, Units Used, Units Remaining)

Invalid licenses are still visible in the Licenses list and in the License Detail drawer, where they display an Invalid chip next to the signature status. This can occur if a deployment is re-provisioned with a new operator keypair, causing previously valid licenses to have a mismatched deployment key.

Disabling and Deleting a License

Disabling a license is primarily a prerequisite for deleting it, but it can also be used on its own to temporarily exclude a license from enforcement. Typical reasons to disable a license:

• Remove an invalid license — A license whose deployment key no longer matches (for example, after the deployment was re-provisioned with a new operator keypair) or whose signature fails verification can be disabled and then deleted to clean up the Licenses list.
• Remove an expired or superseded license — Once a license has been replaced by a newer one and is no longer needed, disable then delete to remove it from the system.
• Temporarily exclude a license from enforcement — For example, while diagnosing a licensing issue with vendor support.

To disable a license:

1. Navigate to Licensing > Licenses and click on a license to view its details in the detail drawer.
2. Click Disable. The license status changes to Revoked and it no longer contributes to the unit pool.
3. A disabled license can be re-enabled by clicking Enable in the detail drawer, provided the license passes signature and deployment key validation. The Enable button is not shown for licenses with an invalid signature or mismatched deployment key.

To permanently delete a license, first disable it, then click Delete in the detail drawer.

When a license is disabled, expires by date, or is otherwise retired, its consumed units are split into two parts:

• In-bucket consumption — units consumed within the license's cap. These retire alongside the license: both the unit pool and the "Units Used" figure drop by the same amount, so remaining capacity is unaffected.
• Overage / carry-debt — units consumed beyond the license's cap (for example, when stacked licenses fall back from one to another). This portion is preserved as platform-wide carry-debt and continues to count against the active pool until offset by new licensed capacity.

This means a clean renewal — letting one license expire while another still has unused capacity — does not push a deployment into enforcement, provided the retiring license was operating within its cap.

warning

Deleting a license is permanent. The license must be re-uploaded from the original vendor file if needed.

What happens when a license expires

The retirement model lets customers manage license lifecycle without surprises:

• Renewing a license: when one license expires and another is added (or already in place), only the units that the retiring license was carrying as overage stay charged to the platform. Units the license paid for inside its own cap retire with it. The Units Used figure drops to reflect what the remaining active licenses are actually carrying.
• Stacking licenses to extend capacity: two licenses A (expiring sooner) and B (expiring later) form a combined pool. Usage is debited from the soonest-expiring license first, overflowing to the next when its cap is reached. When A expires by date, A's in-bucket consumption retires with it; B's remaining headroom is unaffected.
• Overage during the retirement window: if a license retires while it was carrying overage (consumption above its own cap), the overage is preserved as carry-debt. This shows in the Usage tab under Units Remaining and continues to consume new licensed capacity until offset.

The Lifetime consumed figure on the Usage tab is the deployment's total consumption since it was first deployed, summed across every extension regardless of which license paid for it. This is the figure chargeback reports reconcile to. Once any license has retired, Lifetime consumed can be larger than Units Used: the difference is the in-bucket consumption that retired alongside its license cap.

License File Format

A vendor-issued license is a JSON file with the following structure:

Field	Type	Description
identifier	string	Vendor-assigned unique license ID
units	integer	Total units granted by this license
issued_at	ISO 8601	Date the license was issued
expires_at	ISO 8601	Expiry date of the license
grace_period_days	integer	Grace period in days after unit exhaustion or date expiry
customer	string	Customer name
notes	string	Optional vendor notes
unit_rates	object	Conversion rates per extension (see Understanding Unit Rates)
deployment_key	string	Operator public key of the target deployment (obtain from the Upload License drawer)
signature	string	Base64-encoded Ed25519 signature

See Also

• Usage Tracking—Monitor usage and generate reports
• Business Units & Attribution—Attribute usage to business units