Licensing & tiers¶

The VIDAI Control Plane ships in two editions:

Community: free, no expiry, the control plane plus everything you need to run it sensibly.
Enterprise: annual licence, adds compliance routing, ML guardrails, BI exports, webhook delivery, ledger replay, and more.

This page explains what's in each tier, how the licence resolves at startup, what the banner states on the License page mean, and what happens to your data if a licence lapses.

If you just want to know what edition you're running, open the License page in the console; the tier badge at the top of the card answers it in two seconds.

When you'd open this page¶

A new admin starts and wants to know what edition you're on, and what comes with it.
You see an Enterprise pill on a nav item (Webhooks, BI Tables) and wonder what it means.
A compliance auditor needs to know the deployment's licence posture for a filing.
A licence is about to expire and you want to know what happens if it lapses.
A licence has lapsed and you want to know what changes (and what doesn't).
You want to plan a Community → Enterprise upgrade and want the feature list in one place.

What's in each tier¶

This is the full feature matrix. Community is a real production edition; it's not a stripped trial. Enterprise adds the capabilities below on top of everything Community has.

Capability	Community	Enterprise
AI control plane (multi-provider routing, fallback chains, translation)	✓	✓
Regex guardrails (block / mask / redirect / log-only)	✓	✓
Cost engine (live rate-card sync, pricing, chargeback)	✓	✓
Teams + applications (membership, key issuance, per-team budgets)	✓	✓
Rate limits (per-key + role + global RPM caps)	✓	✓
Routing rules (cost-saver, A/B, deny, spend circuit, custom)	✓	✓
Request logs + audit (the everyday observability surface)	✓	✓
Compliance routing (region-pinning + regulatory tagging on rules)	–	✓
Webhooks delivery (HMAC-signed POST destinations + delivery worker)	–	✓
Ledger replay (recompute historical cost ledger after rate-card edits)	–	✓
BI Tables (usage / events / aggregates / audit surfaces for external BI)	–	✓
Rate-card history (SCD2) (manual point-in-time pricing edits)	–	✓
Worker-flag admin (toggle BI aggregate refresher, webhook dispatcher, request-log observer)	–	✓
VidaiGuard ML guardrails (injection / toxicity / PII detection via the ML sidecar)	–	✓

📌 Worth knowing. The Capabilities section on the License page shows you exactly which rows your deployment has unlocked. On Community, the Enterprise rows are listed too, dimmed, so you can see what an upgrade would add.

How the licence works¶

The control plane reads its licence at process startup. The licence is a signed JWT carried in the VIDAI_LICENSE_KEY environment variable. Once the server has decided what tier you're on, that decision is fixed for the lifetime of the process; restart is the only way to transition between tiers.

This "restart-only" rule is deliberate. A licence renewal that silently kicked in mid-traffic could change behaviour while real requests are in flight; treating the licence as a startup-time decision keeps the control plane predictable.

Startup decision tree¶

When the server starts, it walks four steps:

Read the env variable. If VIDAI_LICENSE_KEY is missing or blank, skip to step 4.
Validate signature + claim shape. If the JWT is corrupt or the claims don't match the expected shape, the server logs the failure, flags env_license_invalid, and falls through to step 3.
Try the cached licence. The server keeps a copy of the last-known-good licence on disk so a transient env-glitch doesn't break a running deployment. If the cache exists, is younger than 30 days, and hasn't itself expired, the server runs at the cached tier with the env_license_invalid flag set (so the banner makes the cache-fallback visible).
Run in recovery mode. No working licence anywhere; the server still runs, but with eval caps (25 keys / 5 users) on write-time operations. Existing data is untouched.

⚠️ Watch out. The cache exists for transient env glitches (a typo during an edit, a deploy that briefly didn't see the volume). It's not meant to mask a deliberately cleared licence key, and a cleared key sends the deployment straight to recovery mode, no cache lookup.

The License page renders a banner when something is off about the licence. There are five distinct states; only one fires at a time, and the precedence is set so the most actionable state shows.

B-1: Expires in 30 days or fewer¶

Your Enterprise licence is still valid, but the clock is winding down. The banner shows the days remaining; renewal email comes from the licensing team. Renew + restart at any point in this window and the banner clears.

B-2: In grace period¶

The licence's expires_at has passed, but the 30-day grace window is still open. The server keeps running with full Enterprise features for the duration of this window. Once you restart inside grace with a renewed licence, you're back to normal.

B-3: Recovery mode, env key invalid¶

The licence key in your environment couldn't be parsed and the cache fallback didn't apply (either there's no cache or it's expired). The deployment is running in recovery mode with eval caps. Fix the env key + restart to restore full function.

B-4: Recovery mode, lapsed past grace¶

You had an Enterprise licence; it expired more than 30 days ago; the server has now restarted and the licence isn't renewed. Recovery mode kicks in. Existing data is preserved (see Downgrade behaviour below); writes against Enterprise-only endpoints return a tier-gated error until a licence is installed.

B-5: Running on cached licence¶

The env JWT couldn't be parsed, but the cache fallback applied, so the server is running at the cached tier (typically what you had before the env break). This state is fragile: at the next restart, if the env JWT still can't be parsed, the cache may have expired and the deployment drops to B-3. Fix the env file before that happens.

Recovery mode caps¶

When the server is running in recovery mode (no working licence, banner B-3 or B-4), write-time caps apply:

25 API keys maximum: POST /admin/keys returns a cap-exceeded error once you're at the limit.
5 users maximum: same shape, applied to POST /admin/users.

Existing rows above the caps are never deleted or hidden. If you had 200 keys when the licence lapsed, all 200 keep working. The caps only apply to new writes.

This is deliberate. Recovery mode is a recovery path, not a trial: it lets you evaluate the control plane, recover from a botched deploy, or run a fresh install long enough to install a real licence. It's not a free Enterprise.

The Users tile and API Keys tile on the License page show the current count alongside the cap when recovery mode is active, so you can see how close you are.

Downgrade behaviour¶

If an Enterprise licence lapses past grace and the server restarts to Community / recovery mode, all your existing Enterprise-shaped data stays visible and read-only.

Concretely:

Compliance-tagged routing rules stay live: the control plane continues to apply them at request time. Editing them requires Enterprise.
Webhooks keep delivering. New webhook destinations can't be created on Community; existing ones continue firing.
Manual SCD2 rate-card history is preserved. The history page tab hides on Community, but the underlying point-in-time pricing still applies. Re-enabling Enterprise reveals the tab with the data intact.
BI Tables data is preserved. The page becomes inaccessible on Community; the data underneath is untouched.

Install + restart a fresh Enterprise licence at any point and everything comes back online with no data migration.

💡 Pro tip. The read-only view is the recovery affordance. If you're caught between renewal cycles, the control plane keeps doing the right thing; you just can't change Enterprise policy mid-lapse. A short Community window between Enterprise licences is operationally safe.

Installing or upgrading a licence¶

Licence installation is a paste-and-restart operation:

Get the JWT from the licensing team ([email protected]).
Set VIDAI_LICENSE_KEY=<the-jwt> in your .env (or equivalent secret store for your deployment).
Restart the server.
Open the License page; the tier badge should read Enterprise, and the banner should be gone.

There's no admin UI for licence install on purpose. Licences are deployment-team artefacts; installing one is a config step, not a console click.

Where to go next¶

License: what the License page actually shows you, field by field.
Webhooks: Enterprise feature; how event delivery works.
BI Tables: Enterprise feature; usage / events / aggregates / audit surfaces.
Compliance: Enterprise feature; per-rule policy attribution.
Cost Engine: Community baseline with Enterprise-only Ledger replay + SCD2 history tabs.
Guardrails: Community baseline (Rules tab) with Enterprise-only VidaiGuard tab.