Core Concepts
The portal, the SDK, the four API surfaces, and the central Admin Module — and how a license flows between them.
Understanding these five ideas removes almost all of the confusion newcomers hit. Read this once and the rest of the docs will click.
The three systems
Customer Portal
This web app + API. Customers sign in, buy plans, and manage license keys here.
The SDK
A small client your plugin embeds to validate licenses and meter usage.
Admin Module
A separate, central dashboard that manages every plugin deployment from one place.
A plugin is one product you sell. Each plugin gets its own Customer Portal deployment (this app). The Admin Module sits above all of them, giving you a single operations console across every plugin.
The four API surfaces
The portal's API is split into four surfaces, each with its own auth model. Keeping them straight is the single most useful thing to learn:
| Surface | Path prefix | Who calls it | Auth |
|---|---|---|---|
| Portal API | /api/rpc/*, /api/rest/* | The signed-in customer (web/mobile) | Session cookie |
| Public API | /public/* | Plugin installs in the field | License key + publishable key |
| Webhooks | /webhooks/* | Your billing provider | Provider signature |
| Connector | /connector/* | The central Admin Module | Service token + HMAC |
Never call the Public API with a session cookie, and never expose the Portal API to plugin installs. The surfaces are separate on purpose — each is rate-limited and authenticated differently.
How a license flows end to end
Checkout
A customer picks a plan on the Billing page. The portal creates a hosted checkout session with your billing provider and redirects them to pay.
Webhook reconciliation
After payment, the provider posts an event to /webhooks/billing. The portal
verifies the signature, records the subscription, and issues a license key.
The customer copies their key
The new key appears on their Licenses page in the format
LK-2025-XXXX-YYYY.
The plugin activates
Your plugin calls /public/validate (via the SDK) with the key and a
fingerprint. The install is now a tracked activation.
Ongoing validation + metering
The plugin validates periodically and reports metered usage. Counters reset at the start of each billing period.
Key terms
| Term | Meaning |
|---|---|
| License key | The LK-… string a customer puts into your plugin. |
| Activation | One install (device/site) tied to a license, identified by a fingerprint. |
| Fingerprint | A stable, unique id your plugin generates per install. |
| Entitlements | The limits a license grants (activations, monthly usage, seats). |
| Connector | The authenticated channel the Admin Module uses to manage this deployment. |
Configuration is centralized
Almost everything about a deployment is driven by config files in
packages/config and environment variables — not scattered through the code:
plugin.ts— name, domain, company, slugbranding.ts— colors, logos, theme tokenspricing.ts— plans and limitsproviders.ts— which auth/billing/email provider is activeservices.ts— storage, analytics, monitoring, jobs, i18n flags
See the Reference for the full breakdown.