Licensing

Last updated: 2026-04-10

This guide covers runtime license activation — what it is, how it works, and how to manage it. For Composer repository access and purchasing, see INSTALLATION.md.

Table of Contents

• Overview
• Setup
• How Activation Works
• Deactivating (Domain Transfers)
• Error Reference
• Local Development
• CI/CD and Staging
• FAQ

---

Overview

Runtime activation enforces your plan's site limits (Solo: 2 sites, Agency: 50 sites) inside the running application. On first boot, the package registers your server with Anystack and caches the result locally. Subsequent boots re-use the cache without API calls until it expires (default: 24 hours).

This is separate from Composer access. Your license key serves two purposes:

Purpose	Where used	What it controls
Composer authentication	~/.composer/auth.json	Whether composer require / composer update can download the package
Runtime activation	FILAMENT_ADDRESS_LICENSE_KEY in .env	Whether the installed package activates on boot and enforces site limits

Composer access uses HTTP Basic auth (email + key). Runtime activation uses the same key but calls the Anystack API from your server.

---

Setup

Add your license key to your production .env:

FILAMENT_ADDRESS_LICENSE_KEY=your-license-key-here

That is the only required change. The package reads APP_URL to determine your site fingerprint and activates automatically on the next request.

No artisan commands, no migrations, no publish steps.

---

How Activation Works

First boot

On the first web request after adding FILAMENT_ADDRESS_LICENSE_KEY, the package:

1. Reads APP_URL and extracts the domain (e.g. mysite.com)
2. Calls the Anystack API to activate the license for that domain
3. Stores the activation record in the Laravel Cache

Subsequent boots

If validated_at is within the cache TTL (default 24 hours), the package skips the API call entirely and boots normally. Beyond the TTL, it makes a lightweight validation call to Anystack to refresh expires_at and reset the clock.

Maintenance expiry

When your annual maintenance period expires, expires_at passes. The package logs a warning but continues to work — version gating is handled at the Composer level by Anystack Satis, not at runtime. Your installed version keeps running indefinitely.

Cache TTL

The default re-validation interval is 24 hours. You can adjust it:

FILAMENT_ADDRESS_LICENSE_CACHE_TTL=86400  # seconds (default: 86400 = 24h)

Set higher (e.g. 604800 for weekly) to reduce API calls on high-traffic sites. Setting it lower is rarely useful.

---

Deactivating (Domain Transfers)

Solo licenses cover 2 production sites. If you are moving your site to a new domain, you must release the old activation slot first.

On the old server, run:

php artisan addresses:license:deactivate

This calls the Anystack API to release the activation slot and clears the cached activation record. On the next boot of the new installation, the license activates automatically against the new domain.

If you cannot access the old server (e.g. the server is gone), email support@viewflex.net with your old and new domain. We will release the activation slot manually.

---

Error Reference

Scenario	What happens
Invalid license key	Exception on first boot: "Invalid license key. Check FILAMENT_ADDRESS_LICENSE_KEY in your .env."
Activation limit reached	Exception on first boot: "License activation limit reached. Solo licenses cover 2 sites, Agency licenses cover 50. Email support@viewflex.net…"
Anystack API unreachable	Warning logged, boot continues — your site never goes down because of a licensing API outage
Maintenance expired	Warning logged, boot continues — use your current version, renew to get updates
Corrupt activation record	Re-activates from scratch on next boot

Exceptions on first boot are intentional — an invalid key or exceeded limit should be caught during deployment, not silently ignored.

---

Local Development

License checks are skipped automatically when APP_ENV=local. You can set the key in your local .env (e.g. copied from production) and it will never trigger activation or consume a slot.

APP_ENV=local
FILAMENT_ADDRESS_LICENSE_KEY=your-key  # safe — skipped in local environment

If you prefer not to set the key locally at all, that works too — an unset key is also silently skipped.

---

CI/CD and Staging

License checks are skipped automatically when APP_ENV=testing. CI pipelines running with APP_ENV=testing will never trigger activation regardless of whether the key is set.

For staging environments (APP_ENV=staging or production), the key IS checked. You have two options:

Option A — No key: Leave FILAMENT_ADDRESS_LICENSE_KEY unset on staging. The package skips activation silently.

Option B — Key set, staging domain: Add the key and treat staging as one of your plan's sites. Solo licenses cover 2 sites, so staging + production is within limit.

---

FAQ

Does composer install in CI trigger an activation?

No. Composer install only downloads package files. Activation only happens when the PHP application boots and handles a web request — php artisan commands and unit tests are skipped entirely.

Does running php artisan locally trigger an activation?

No. The boot hook skips console commands, unit tests, and any environment where APP_ENV is local or testing.

What is the site fingerprint?

The domain extracted from APP_URL in your .env (e.g. mysite.com from https://mysite.com). This is what Anystack records as your activation. Two sites with different APP_URL values are counted as two activations.

Can I see my active activations?

Yes — log into your license portal to see which domains are currently activated against your license.

What happens if I deploy to a new server with the same domain?

Nothing special — the new server activates normally using the same fingerprint. Anystack deduplicates by fingerprint, so re-deploying to the same domain does not consume an additional activation slot.

What if APP_URL is not set?

The package falls back to gethostname(). This is unusual in production — you should always have APP_URL set correctly.

Where is the activation record stored?

In the Laravel Cache under the key filament-address-pro.license-activation. It is not a file — there is nothing to commit or gitignore. The record is kept for 365 days and refreshed automatically within your configured FILAMENT_ADDRESS_LICENSE_CACHE_TTL.

What if I need to reset the activation record manually?

Run php artisan cache:forget filament-address-pro.license-activation. The package will re-activate on the next request. Use this if the record becomes corrupt or if you need to force a fresh activation check.