Issue and validate license keys with Polar

Manage license keys as a Polar benefit, validate and activate keys from end-user machines, and retrieve a customer’s keys through the Billable trait.

License keys are a native benefit type in Polar — ideal for desktop applications, paid CLIs, SDKs, and anything that needs an offline-checkable credential issued at purchase time.

The package exposes three surfaces:

1. Admin management — list, fetch, and update keys using your org-scoped access token.
2. Public verification — validate, activate, and deactivate from end-user machines (no admin token required).
3. Billable accessor — retrieve a customer’s keys from the Billable trait using a server-side session.

License keys are created automatically by Polar when a customer purchases a product that has the license key benefit attached. You don’t create them programmatically — you manage and validate them.

Configuration

The public verification methods — validateLicenseKey, activateLicenseKey, and deactivateLicenseKey — require a Polar organization ID. Set it once in your .env and the package will pick it up automatically on every call:

POLAR_ORGANIZATION_ID="your-org-id"

If you need to call these methods for multiple organizations, you can pass the ID explicitly on each call (see below).

Admin management

Use the LaravelPolar facade with your org-scoped access token. These methods derive the organization from the token itself, so no extra configuration is needed.

use Danestves\LaravelPolar\LaravelPolar;
use Polar\Models\Components;

// List all license keys (optional filters: organizationId, benefitId, page, limit)
$response = LaravelPolar::listLicenseKeys();

// Fetch a single key with its activations
$key = LaravelPolar::getLicenseKey('lk_xxx');
// Returns Components\LicenseKeyWithActivations

// Update a key — e.g. raise the activation limit
LaravelPolar::updateLicenseKey('lk_xxx', new Components\LicenseKeyUpdate(
    limitActivations: 10,
));

getLicenseKey() returns a LicenseKeyWithActivations object, which includes the full list of current activations on the key.

Public verification

These methods are designed to be called from end-user machines (a desktop app, a CLI, a native SDK). They do not require an org-scoped admin token; they resolve the organization ID from polar.organization_id in your config (or from an explicit argument).

Validate a license key

Check whether a key is valid. Optionally bind the validation to a specific activation:

$validated = LaravelPolar::validateLicenseKey(
    key: 'LIC-XXXX-XXXX-XXXX',
    activationId: 'act_xxx', // optional — omit to validate the key itself
);

Activate a key on a new device

Record a new activation against a key. Pass a human-readable label and optional meta properties:

$activation = LaravelPolar::activateLicenseKey(
    key: 'LIC-XXXX-XXXX-XXXX',
    label: 'My MacBook Pro',
    meta: [
        'hostname' => 'macbook-pro',
        'os' => 'darwin',
    ],
);
// Returns Components\LicenseKeyActivationRead
// $activation->id — save this as the activationId for future validate/deactivate calls

Deactivate an activation

Remove an activation when a customer uninstalls or transfers their license:

LaravelPolar::deactivateLicenseKey(
    key: 'LIC-XXXX-XXXX-XXXX',
    activationId: 'act_xxx',
);

Explicit organization ID override

Pass organizationId as a named argument on any public verification call to override the config value:

LaravelPolar::validateLicenseKey(
    key: 'LIC-XXXX-XXXX-XXXX',
    organizationId: 'org_xxx',
);

If neither POLAR_ORGANIZATION_ID is set in your config nor an explicit organizationId is passed, the package throws an \InvalidArgumentException. Always ensure the organization ID is available before calling the public verification methods.

Listing a customer’s license keys

Use the Cashier-style accessor on your billable model to retrieve the keys owned by a specific customer. The method mints a short-lived customer session under the hood, so your admin token is never exposed.

// All keys for the customer
$keys = $user->licenseKeys();
// Collection<int, Components\LicenseKeyRead>

// Scoped to a single benefit
$keys = $user->licenseKeys(benefitId: 'b_xx');

Filtering by benefitId is useful when you sell multiple products that each grant different license keys and you want to retrieve only the key associated with a specific benefit.