Migration

0.2.0 -> 0.3.0

Version 0.3.0 is an additive release. Existing API integrations can continue running without a manual database migration. Offline license support is opt-in per slug and requires signing-key configuration before tokens are issued.

What changed

  • Built-in management UI can be served from the Docker image with UI_ENABLED=true.
  • New license registry endpoint: GET /management/licenses.
  • New webhook run log endpoint: GET /management/webhooks/deliveries.
  • Offline JWT license support is now available per slug.
  • New offline signing key endpoints under /management/offline/*.
  • POST /validate can return a refreshed offline token when the license's slug has offline enabled.
  • The Webhooks UI now shows recent delivery attempts, statuses, response codes, and errors.
  • The management UI includes license listing, generation, revocation, slug management, API keys, webhooks, and offline licenses.

Required actions

  • Pull or rebuild the 0.3.0 Docker image.
  • No manual database migration is required for existing 0.2.0 installations; startup schema migration adds the offline columns and signing key table.
  • No environment variable changes are required unless you want to enable the bundled UI or use offline signing.

Optional: enable the UI

Set UI_ENABLED=true to serve the bundled management console from the same Docker image as the API. The console uses your management API key for operator actions.

Optional: enable offline licenses

Offline tokens are controlled per slug with offline_enabled and offline_token_lifetime_hours. All slugs, including the seeded default slug, default to offline-disabled unless you turn the setting on.

  • Set OFFLINE_SIGNING_ENCRYPTION_KEY to a stable secret of at least 32 characters before creating signing keys.
  • Optionally set OFFLINE_TOKEN_ISSUER and OFFLINE_TOKEN_AUDIENCE.
  • Configure token lifetime per slug with offline_token_lifetime_hours; it defaults to 24.
  • Create and activate an Ed25519 signing key from the Offline Licenses UI or management API.
  • Export active and verify-only public keys and ship them with clients that validate licenses offline.

Integration notes

  • Continue using generated server API keys for /generate and /revoke.
  • Use GET /management/licenses for admin license registry screens and reporting.
  • Use GET /management/webhooks/deliveries for webhook delivery debugging and support workflows.
  • Treat the new token response field on /activate and /validate as optional; it is omitted when the slug is not offline-enabled or no active signing key exists.