License a CAD or architecture plugin
This is a step-by-step technical guide to adding a license screen to your product: it has code to copy and API calls to make. If you sell the product but don't write its code, read Not a developer? Start here and send this page to your developer.
This covers add-ins for Revit, AutoCAD, Rhino and Grasshopper, SketchUp, ArchiCAD, and similar design tools. A license is usually per workstation. The customer pastes the key into a small dialog, the add-in activates that computer, and it re-checks in the background.
Licensr does not host your installer. Host it on your own website or the tool's app store and link your buy page from there.
Design offices often block unknown web addresses. Tell your customers to allow api.licensr.app on port 443. If that is not possible, see offline tokens.
Product settings
| Setting | Value |
|---|---|
| Activation mode | Seat: one activation per workstation. |
| Client type | Native app. Add-ins send no browser Origin. |
| Identifier | A random GUID your add-in creates once and saves in the user's app data folder. |
Create a plan
In the admin panel, open your product and add a plan: one price with a limit on how many devices or websites one key can be used on. Keep the defaults if you are unsure. You can add more plans later. See the Quick start.
Also create a Client API key on the product (shown once, starts with pk_test_ or pk_live_). This is the key you put in your product.
Get a test license
You do not have to pay to try your integration. In the admin panel go to Customers → Issue license, enter your own email, pick the product and plan, and issue it. The key (starts with lic_) arrives by email and is shown once on screen. The dashboard checklist has a shortcut for this.
Use your pk_test_ key against https://api.staging.licensr.app while you build, then switch to pk_live_ and https://api.licensr.app when you release.
What your license screen must do
Your product needs one small screen: a text box for the key, an Activate button, and a Deactivate button. It follows these rules, whatever the platform:
- Activate, then validate. When the customer clicks Activate, call activate (this registers the device or website against the plan's limit), then validate. Unlock only if the validate response has
valid: true. Save the key and theactivation_idfrom the activate response. - Check again in the background. Call validate at every launch and about once a day while the product runs. A refund, a cancelled subscription, or an expired license happens after the sale, and this daily check is how your product finds out. Without it, a refunded key keeps working forever.
- Lock immediately on
valid: false. If Licensr cannot be reached, stay unlocked (optionally lock after a few days with no answer). Try again later. - Offer a Deactivate button. It calls deactivate with the saved
activation_id, forgets the key, and locks the product. This lets a customer move to a new computer without asking you for help.
Messages to show when activate fails (read detail.error in the response):
| Code | Say |
|---|---|
license_not_found | "We could not find that key. Check for typos." |
activation_cap_exceeded | "This key is already in use on the maximum number of devices. Deactivate it on another device first." |
license_inactive | "This license is no longer active. Contact the seller." |
| no response at all | "Could not reach the license server. Try again." |
| any other code | "Something went wrong (code)." Show the code so the customer can send it to you. |
The full list is in Errors.
Revit, AutoCAD, Rhino (C# / .NET)
Use the C# SDK: dotnet add package Licensr.Sdk. Keep the saved state in a small file under %APPDATA% (or the macOS equivalent).
The C# SDK needs .NET Core 3.0+ / .NET 5+. It works in Revit and AutoCAD 2025+ and Rhino 8. Older versions run on .NET Framework 4.8, where the SDK does not load. For those, keep the same dialog and saved file, but make the three calls yourself with HttpClient. The any-language guide shows the requests and answers.
using System.Text.Json;
using Licensr.Sdk;
public static class MyAddinLicense
{
static readonly string StatePath = Path.Combine(
Environment.GetFolderPath(Environment.SpecialFolder.ApplicationData), "MyAddin", "license.json");
record State(string DeviceId, string? Key, string? ActivationId);
static State Load()
{
if (File.Exists(StatePath)) return JsonSerializer.Deserialize<State>(File.ReadAllText(StatePath))!;
return new State(Guid.NewGuid().ToString(), null, null); // created once
}
static void Save(State s)
{
Directory.CreateDirectory(Path.GetDirectoryName(StatePath)!);
File.WriteAllText(StatePath, JsonSerializer.Serialize(s));
}
static LicensrClient NewClient(string deviceId) => new LicensrClient(new LicensrClientConfig
{
ApiKey = "pk_live_...", // Client key, safe to ship in the add-in
PluginSlug = "my-addin",
DeviceId = deviceId,
});
// User clicked "Activate" in your dialog. Returns an error message, or null on success.
public static async Task<string?> Activate(string licenseKey)
{
var state = Load();
var client = NewClient(state.DeviceId);
try
{
var activation = await client.ActivateAsync(new ActivateRequest
{
LicenseKey = licenseKey,
ActivationType = ActivationType.Seat,
Identifier = state.DeviceId,
Label = Environment.MachineName,
});
var check = await client.ValidateAsync(new ValidateRequest { LicenseKey = licenseKey });
if (!check.Valid) return "This license is not active.";
Save(state with { Key = licenseKey, ActivationId = activation.ActivationId });
return null;
}
catch (LicensrApiException e) when (e.Code == "activation_cap_exceeded")
{
return "This key is already used on the maximum number of computers.";
}
catch (LicensrApiException) { return "We could not activate that key."; }
catch (LicensrNetworkException) { return "Could not reach the license server."; }
}
// At add-in load (pass true if a key is saved), and again from a timer about once a day (pass the current state).
public static async Task<bool> StillValid(bool previous)
{
var state = Load();
if (state.Key is null) return false;
try { return (await NewClient(state.DeviceId).ValidateAsync(new ValidateRequest { LicenseKey = state.Key })).Valid; }
catch (Exception) { return previous; } // offline, rate limited or server error: keep the previous state
}
// User clicked "Deactivate".
public static async Task Deactivate()
{
var state = Load();
if (state.Key is not null && state.ActivationId is not null)
{
try
{
await NewClient(state.DeviceId).DeactivateAsync(
new DeactivateRequest { LicenseKey = state.Key, ActivationId = state.ActivationId });
}
catch (LicensrNetworkException) { }
}
Save(state with { Key = null, ActivationId = null });
}
}
Call StillValid(...) when your add-in loads (for Revit, in OnStartup) and from a System.Timers.Timer every 24 hours. Show your dialog from a ribbon button.
SketchUp (Ruby), ArchiCAD (C++), Grasshopper (Python)
- ArchiCAD add-ons written in C++ can use the C++ SDK.
- SketchUp extensions (Ruby) and Rhino or Grasshopper scripts (Python) call the three HTTPS endpoints directly. Follow the any-language guide.
Link your buy page
Licensr does not host your download. Host the file on your own website or store, then add a Buy button that links to your Licensr buy page (the dashboard shows the full link, which looks like /buy/your-slug). Customers pay there and get their key by email, then paste it into your license screen.
Go live
- Swap your
pk_test_key for thepk_live_key and usehttps://api.licensr.appin the release build. - Buy your own product once, using the buy page, to see the whole flow.
- Check the dashboard: the Get started checklist shows You're live! when payments, a product, a plan, a test license, and a first check from your product are all done.
Stuck? The license calls guide lists every field and error.