Migration Guides

Version-to-version and vendor-migration notes for integrators. Breaking public contract changes should land here (and in the Changelog) in the same docs wave as the code (EN+RU).

How to use this section

Situation	Where to look
Runtime / OpenAPI breaking change	Entry below + API Reference
Error code rename / retire	Error catalog
SDK major bump	Package changelog in the public SDK repo (SDKs)
Key / device identity policy	License Keys · Device Identity
Trust / crypto profile	Verify trust (JWKS)

Published migrations

Wave 74.15

Canonical License and Edge Gateway authority cutover — 2026-08

Wave 74.15 retires three compatibility paths that could bypass canonical Product and Customer identity. This is a behavioral cutover without a schema deletion: existing License rows, signed artifacts, and legacy Relay storage are not rewritten, but they cannot supply authority for new decisions.

Affected paths and replacements

Retired path	Current result	Replacement
POST /api/v1/licenses	410 with license_legacy_compatibility_disabled	Issue from a validated Subscription through POST /api/v1/licenses/subscription-issues; see Subscription License issue
POST /api/v1/licenses/bulk/create	410 with license_legacy_compatibility_disabled	Issue each eligible Subscription through the canonical issue workflow; do not synthesize Product or Customer identity in a bulk body
Offline request compatibility productId input	Accepted for source compatibility but ignored	Resolve Product from the current verified License runtime snapshot; treat a mismatch or missing snapshot as deny
Local Relay with only legacy entitlement rows or a historical code-derived lease	Validate and refresh deny with relay.host.no_snapshot	Enroll the Gateway and apply a current signed V2 bundle containing the License snapshot before LAN activation, validation, or refresh

entitlement.Code remains a feature or limit identifier. It must never be copied, parsed, or transformed into ProductId. Request fields, configuration, default, and unknown are also not Product authority.

Existing License reads and lifecycle operations remain available according to their normal state. Public request and response shapes retained for compatibility do not imply that their deprecated fields still carry authority.

Preflight

1. Inventory every integration that calls either retired generic create route, sends offline request ProductId as authority, or runs a Local Relay without V2 Gateway bundle synchronization.
2. For every new License, verify an exact same-tenant Product, Customer, Published OfferVersion, active CustomerSubscription, and immutable policy snapshot before issue.
3. Move issue traffic to POST /api/v1/licenses/subscription-issues and use a fresh stable Idempotency-Key per logical attempt.
4. Upgrade and enroll each Local Relay, complete signed V2 bundle pull/ack, and confirm the target License is present in the active generation. A legacy entitlement count is not readiness evidence.
5. In a non-production environment, confirm the two retired create routes return 410, offline artifacts carry the snapshot ProductId, and LAN validate/refresh succeeds only after V2 snapshot delivery.

Cutover

1. Stop producers of generic single and bulk License creates.
2. Deploy the canonical Cloud issue integration and verify its durable receipt before enabling the next producer.
3. Regenerate offline request/response artifacts through the current flow. Do not edit or re-sign historical artifacts to insert an inferred ProductId.
4. Synchronize and acknowledge a current V2 bundle on every Relay before directing LAN clients to it.
5. Monitor the stable shutdown codes. license_legacy_compatibility_disabled identifies a producer that has not migrated; relay.host.no_snapshot identifies missing V2 local authority, not an entitlement or offline-grace condition.

Recovery

• If canonical License issue is denied, keep issue traffic stopped and repair the missing Product, Customer, Subscription, OfferVersion, or policy owner evidence. Do not fall back to either generic route.
• If offline issuance has no valid snapshot, restore the canonical runtime snapshot and create a new request. Do not trust the ignored request ProductId or replay an artifact with mismatched identity.
• If Relay returns relay.host.no_snapshot, restore outbound connectivity or apply a current trusted V2 air-gap bundle, then verify its active generation. Offline grace and historical code-derived leases cannot bypass this state.

Rollback boundary

Rollback means pausing traffic or rolling forward with repaired canonical evidence. Rolling back to software or configuration that re-enables legacy writes, request ProductId authority, or entitlement.Code-derived leases is unsupported and unsafe. Wave 74.15 performs no destructive cleanup, so historical data remains available for diagnosis. Schema/table deletion, historical rewrites, and cleanup readiness belong to separately approved Wave 74.15.5.

Related

• Changelog · Production checklist · Troubleshooting

Next steps

• Getting Started
• Releases and updates