A Beekon licence is a signed token (a license-format-v1 JWS) that the SDK verifies on the device, with no network call. The SDK reports its status and never acts on it: no status blocks, degrades or delays anything. Without a key, Beekon runs in evaluation mode and works the same.
This page says which licence you need, how to get a key, and how the SDK reads it. The optional build-time licence gate is not published yet.
Which licence you need
Section titled “Which licence you need”The Client SDK licence covers all four SDKs (Android, iOS, Flutter and React Native) for the app ids it lists. Which one you have follows from your Beekon Cloud account:
| You are | Your licence | Updates it covers |
|---|---|---|
| An individual: one person, building your own apps | Individual, free. | SDK versions released up to 12 months after the account was set up as an individual. Renew updates in the console, free and at any time, moves that date to 12 months from the day you renew. |
| An organisation: a company or a team | Organisation: a lifelong licence, bought once, with one year of maintenance. Renew maintenance a year at a time. | SDK versions released until maintenance ends. |
| On Growth or Scale (either kind of account) | Included with the Cloud plan, at no extra cost. Free does not include it. | SDK versions released while the plan is paid, plus 30 days. |
| An organisation with none of the above | None: the SDK runs in evaluation. | Evaluation works the same and suits development; production apps need a licence. |
Lifelong means that an SDK version released while you were covered stays licensed for good.
When cover ends (maintenance not renewed, or a Growth or Scale plan ended), apps built with
covered versions keep reporting licensed. Only SDK versions released after that date report
updateEntitlementLapsed, and even then the SDK keeps working in full. The key has no expiry
date: what it carries is the last release date it covers.
Individual and Organisation are the account kinds you choose when you sign up. An individual account has one member; to invite people, switch it to an organisation (see Account kind). Prices are not published yet: see the console’s plan picker.
Get a key
Section titled “Get a key”Keys are made in the Beekon Cloud console, under Organisation › SDK licence (owners and admins).
- Add each app by its exact id: the Android
applicationIdor the iOS bundle id, such ascom.acme.driver. Wildcards are not accepted. Builds whose id ends in.dev,.debug,.staging,.qaor.testare covered automatically, socom.acme.driver.debugneeds no entry of its own. Your licence allows a number of apps; the console shows how many. Add app suggests the ids of your projects’ apps that aren’t on the licence yet, and each app’s row in a project’s Apps tab can add its id with one click. - Copy the key. The console shows the newest key, masked, with Copy. One key covers every app you added, on all four platforms.
- Supply it to the apps that set a key in code or in the manifest or
Info.plist(below). Apps in Cloud mode get it automatically.
Each change to the apps makes a new key, and the console says what changed, for example “This key
adds com.acme.driver”. Paste the new key into apps that set licenseKey in code. An app whose id
you removed reports invalid(appIdMismatch) once it uses the new key. The console also lists
every key made for the organisation, newest first.
In Cloud mode
Section titled “In Cloud mode”In Cloud mode the server sends the organisation’s newest key
with the project’s config, and the SDK applies it. There is no licenseKey to set. Register the
app’s id under Organisation › SDK licence as above: a device whose app id is not in the key
reports invalid(appIdMismatch), a log line only.
A key set in the manifest or Info.plist takes priority over the delivered one. If your app sets
one, it is used instead.
The SDK keeps the last delivered key on the device with the time the config was last fetched successfully:
- A delivered key that fails verification never replaces a cached key that verifies.
- The cached key is used for 30 days after the last successful config fetch, by the device’s
clock. Past that the status is
evaluation, and the SDK logs[Beekon][license] The cloud-delivered license has not refreshed for 30 days; running in evaluation until the next successful config fetch.The next successful fetch restores the key. - If the server stops delivering a key (the licence was revoked), the cached key ages out the same way.
Android and iOS keep the key this way from SDK 0.6.0; SDK 0.5.0 applied each delivered key without the cache. Flutter and React Native follow the native SDK of the platform they run on.
Supply a key
Section titled “Supply a key”A key passed to configure overrides one set in the app’s manifest (com.getbeekon.sdk.license meta-data on Android, BeekonLicenseKey in Info.plist on iOS). A token is bound to your app id and platform, so it is safe to commit to source control.
// a license-format-v1 tokenBeekon.configure(BeekonConfig.Local(licenseKey = "eyJ…"))try await Beekon.shared.configure(BeekonConfig.local(licenseKey: "eyJ…"))await Beekon.instance.configure( BeekonConfig.local(licenseKey: 'eyJ…'), // a license-format-v1 token);// a license-format-v1 tokenawait Beekon.configure({ mode: 'local', licenseKey: 'eyJ…' });Read the status
Section titled “Read the status”licenseStatus is the current status. To follow changes, use licenseStatusUpdates on iOS and Flutter, onLicenseStatus on React Native, or collect the Beekon.licenseStatus StateFlow on Android. The status is one of notDetermined, evaluation, licensed(tier, entitlements), expired, updateEntitlementLapsed or invalid(reason).
when (val s = Beekon.licenseStatus.value) { is LicenseStatus.Licensed -> Log.d("beekon", "licensed: ${s.tier}") is LicenseStatus.Evaluation -> Log.d("beekon", "evaluation mode") is LicenseStatus.Invalid -> Log.d("beekon", "invalid: ${s.reason}") else -> {}}// Beekon is an actor, so reading the property needs await.switch await Beekon.shared.licenseStatus {case let .licensed(tier, _): print("licensed: \(tier)")case .evaluation: print("evaluation mode")case let .invalid(reason): print("invalid: \(reason)")default: break}// The current status; subscribe to Beekon.instance.licenseStatusUpdates// for changes.switch (await Beekon.instance.licenseStatus()) { case Licensed(:final tier): print('licensed: $tier'); case Evaluation(): print('evaluation mode'); case Invalid(:final reason): print('invalid: $reason'); default: break;}// The current status; subscribe with Beekon.onLicenseStatus((s) => …) for changes.const s = await Beekon.licenseStatus();switch (s.status) { case 'licensed': console.log('licensed:', s.tier); break; case 'evaluation': console.log('evaluation mode'); break; case 'invalid': console.log('invalid:', s.reason); break; default: break;}The reason of invalid(reason) is one of these, with the platform’s casing (Android Reason.UnknownKey, iOS .unknownKey, Flutter LicenseInvalidReason.unknownKey, React Native 'unknownKey'):
reason | Meaning |
|---|---|
malformed | The token can’t be parsed: bad encoding or structure, a disallowed header, or a claim of the wrong type. |
unknownKey | Signed with a key this SDK version doesn’t know. Update the SDK. |
badSignature | The signature does not verify. |
appIdMismatch | The token’s app_ids don’t include this app’s id. |
productMismatch | The token’s products don’t include this platform. |
unsupportedVersion | The token’s claim format is newer than this SDK understands. |
A token carries claims the SDK reads but never enforces: products (the platforms it covers), app_ids (the app ids it is bound to), tier, max_release_stamp (the last SDK release date it covers), entitlements and an optional exp. A key from the console has tier individual, organisation or cloud, covers all four products, and has no exp. To get one, see Which licence you need and Get a key.
The build-time licence gate
Section titled “The build-time licence gate”Beekon also has a build-time gate: a tool your app adds to its own build that fails a
release build when no usable licence is configured. It runs offline, on your machine or CI,
never in your app. Debug builds always pass (on iOS, the configuration named Debug), and nothing about it changes what the SDK does at run
time. It is opt-in, and it is not anti-tamper: an app that leaves it out is not checked.
How the gate works, for when it ships
The gate reads the key only from the manifest or Info.plist. A key passed only to configure
is invisible at build time, so declare it there too, or acknowledge evaluation (below).
| Licence status at build time | Release build |
|---|---|
licensed | Passes. |
expired, updateEntitlementLapsed | Passes, with a warning. |
evaluation (no key) or invalid | Fails, unless evaluation is acknowledged; then it passes with a warning. |
A Gradle plugin, io.github.beekonlabs.license-gate, applied in the app module. It adds a
checkBeekonLicense<Variant> task to the assemble and bundle tasks of every variant whose build
type is not named debug, and
reads the merged manifest:
- the key:
com.getbeekon.sdk.licensemeta-data, or-Pbeekon.licenseKey=…on the Gradle command line (for CI); - the evaluation acknowledgment:
com.getbeekon.sdk.evaluationModemeta-data set totrue.
A command-line tool, beekon-license-gate, run from a Run Script build phase in the app target. It gates every configuration except one
named Debug, so a custom configuration such as Staging is gated too. It reads the processed
Info.plist at $(TARGET_BUILD_DIR)/$(INFOPLIST_PATH):
- the key:
BeekonLicenseKey, or theBEEKON_LICENSE_KEYenvironment variable; - the evaluation acknowledgment:
BeekonEvaluationModeset to the BooleanYES(a string does not count), orBEEKON_EVALUATION_MODE.
With user script sandboxing on (ENABLE_USER_SCRIPT_SANDBOXING = YES, the default for projects
created in recent Xcode versions), the script can read only the files it declares. Add
$(TARGET_BUILD_DIR)/$(INFOPLIST_PATH) to the Run Script’s Input Files. Without it the tool
sees an empty Info.plist, finds no key, and fails the build as evaluation.
A non-zero exit fails the build, with the reason on stderr.
Android needs nothing extra: the plugin’s manifest tells the Android gate that the product is
flutter. On iOS, set BEEKON_PRODUCT=flutter in the Run Script, or add BeekonProduct =
flutter to the app’s Info.plist.
Android needs nothing extra: the library’s manifest tells the Android gate that the product is
rn. On iOS, set BEEKON_PRODUCT=rn in the Run Script, or add BeekonProduct = rn to the
app’s Info.plist.