Versioning

Quick summary

The REST API uses /api/v1; the entitlement wire contract is also v1 but has no negotiated version field yet.

Use the SDK↔backend compatibility matrix before updating dependencies. A newer package does not imply automatic wire compatibility.

Honest answer: there is no negotiation

The REST surface is prefixed /api/v1, and the license wire is contract v1 — implicit: no version field exists in entitlement claims, headers, or envelopes, and no negotiation logic exists in sdk/license/* (known-limitations §3.2, NOT_IMPLEMENTED).

What "v1" means today

Compatibility is "same contract generation" — every component agrees on the current shape; there is no mechanism to speak v0 or v2:

Component	Version	Contract
@yetdapay/license-web / -server / -nuxt	0.1.0	wire v1
@yetdapay/cli (yp)	0.2.0	local tooling; no license wire calls yet
@yetdapay/sdk	0.1.0	donation/feedback REST
yetdapay-mcp / yetdapay-mcp-gateway	0.1.0	MCP protocol 2024-11-05, REST client
Backends	repo SHA-versioned	REST /api/v1/**; PoP wire v1 (Worker only)

Known wire-v2 candidates

Deferred items that would change the token/contract format when decided (matrix §5):

• aud in Worker entitlements (DEFERRED — neither emitted nor verified).
• tenant_id in Worker entitlements (DEFERRED — same wire-format impact).
• Error-code convergence (INVALID_PUBLIC_JWK, CAPABILITY_INVALID, PAYLOAD_TOO_LARGE, INVALID_STATUS) — documented deltas today; unification is a wire-v2 decision, not a doc fix.

Interop caveat (documented blocker)

SDK defaults (activatePath: /api/license/activate, iss: devpay, optional aud) do not match Worker values (/api/v1/licenses/activate, iss: devpay-lic, no aud). Mutual interop is proven only with explicit config — the createWorkerConfig() presets on both sides are the supported bridge (see SDK worker preset and contract matrix §3).