A Figma plugin runs only when someone starts it, in a sandbox with its own rules for the network and for storage. That changes three things about a license check: the manifest must allow the host, the check happens at plugin start and not on a timer, and “a device” is better modeled as a Figma user. This page covers the online part. The signed-token fallback for when the network is down is in offline verification in a Figma plugin.
manifest.json
{
"name": "Inkwell",
"id": "1234567890123456789",
"api": "1.0.0",
"main": "code.js",
"ui": "ui.html",
"editorType": ["figma"],
"permissions": ["currentuser"],
"networkAccess": {
"allowedDomains": ["https://clavem.io"]
}
}
networkAccess.allowedDomains lists the origins the plugin may call. Figma’s documentation recommends plain fetch in the main thread, and says plugin iframes have a null origin and can call only APIs that answer Access-Control-Allow-Origin: *. Clavem’s License API sends that header, so either route works. The currentuser permission is required to read figma.currentUser.
The calls
// src/licensing.js: runs in the plugin's main thread, which has fetch and figma.clientStorage.
import { check, sha256Hex } from './token.js';
const BASE = 'https://clavem.io';
const PRODUCT_ID = 75; // from your product page
const PUBLIC_KEY = 'kq1…your key…9fA'; // from your product page
const SALT = 'com.example.inkwell';
async function post(action, body) {
try {
const res = await fetch(`${BASE}/v1/licenses/${action}`, {
method: 'POST',
headers: { 'content-type': 'application/json' },
body: JSON.stringify(body),
});
return { status: res.status, body: await res.json().catch(() => ({})), retryAfter: Number(res.headers.get('retry-after')) || null };
} catch {
return null; // offline, DNS failure, blocked domain
}
}
const load = () => figma.clientStorage.getAsync('license');
const save = (license) => figma.clientStorage.setAsync('license', license); // objects are allowed
const clear = () => figma.clientStorage.deleteAsync('license');
/** 'licensed' | 'invalid' | 'needs-network' | 'unlicensed'. Call it when the plugin starts. */
export async function checkLicense(now = Date.now() / 1000) {
const saved = await load();
if (!saved) return 'unlicensed';
const r = await post('validate', { license_key: saved.key, instance_id: saved.instanceId });
if (r?.status === 200 && typeof r.body.valid === 'boolean') {
await save({ ...saved, token: r.body.token ?? saved.token }); // also when not valid: offline, the token then says so
return r.body.valid ? 'licensed' : 'invalid';
}
if (r?.status === 404) { await clear(); return 'invalid'; } // unknown key, or this seat was removed
// No answer, 429 (Retry-After: 60) or 503 (Retry-After: 5): trust the stored token while it is fresh.
return check(saved.token, { publicKey: PUBLIC_KEY, productId: PRODUCT_ID, fingerprint: await fingerprint(), now }) === 'ok' ? 'licensed' : 'needs-network';
}
A known key always answers 200, valid or not, so read valid. A 404 is an unknown key or instance_id not found. A 429 or 503 says nothing about the license, so the plugin trusts the stored token and tries again the next time it runs. There is no background timer to retry on, because the plugin only runs while it is open.
A seat per Figma user
Figma gives a plugin no hardware id and no device. What it does give, with the currentuser permission, is figma.currentUser.id. Hash it, and one Figma user holds one seat, wherever they run the plugin:
async function fingerprint() {
let id = figma.currentUser?.id; // null for a user who is not logged in
if (!id) { // fall back to a random id kept on this machine
id = await figma.clientStorage.getAsync('installId');
if (!id) { id = Date.now().toString(36) + Math.random().toString(36).slice(2); await figma.clientStorage.setAsync('installId', id); }
}
return sha256Hex(`${SALT}:${id}`);
}
export async function activate(key) {
const r = await post('activate', { license_key: key, instance_name: `Figma: ${figma.currentUser?.name ?? 'user'}`, fingerprint: await fingerprint() });
if (!r) return { state: 'unavailable' };
if (r.status === 200 && r.body.instance?.id && r.body.token) {
await save({ key, instanceId: r.body.instance.id, token: r.body.token });
return { state: 'activated' };
}
const lic = r.body.license_key;
if ((r.status === 400 || r.status === 404) && lic?.activation_usage >= lic?.activation_limit && /activation limit/.test(r.body.error ?? ''))
return { state: 'limit-reached', used: lic.activation_usage, limit: lic.activation_limit };
return r.status === 400 || r.status === 404 ? { state: 'refused', reason: r.body.error } : { state: 'unavailable', retryAfter: r.retryAfter };
}
clientStorage lives on one computer, so the same person on a second machine has to enter the key again. With the fingerprint they get the same seat back and use no second one. The license limit then counts Figma users, which is usually what a plugin seller means by “3 seats”. A user who is not logged in gets a random id, and each such machine takes its own seat.
Storage
Figma documents figma.clientStorage as storing data on the user’s local machine, asynchronously, like localStorage, specific to your plugin id, and not synchronized across users. It allows objects, and the quota is 5 MB per plugin. The documentation also says to expect that clearing browser data can clear it, so treat a missing license as “ask again”. Do not use figma.root.setPluginData for the key. That data lives in the document, and everyone who opens the file can read it.
What the code returned
before: unlicensed
activate: { state: 'activated' }
same user, second computer, same seat: activated true
online: licensed
server down: licensed
limit: { state: 'limit-reached', used: 3, limit: 3 }
The stub returned the first seat’s instance id again.
Pitfalls specific to Figma
- A domain missing from the manifest fails the call like an offline network. Test with
allowedDomainsset before you publish. - Ask the main thread, not the UI. Keep
fetchand the key incode.jsand send the UI only a state string withfigma.ui.postMessage. - Add your own timeout. The sketch has none, because the plugin sandbox may not provide
AbortSignal.timeout. Race thefetchagainst asetTimeoutpromise withPromise.race, so a dead network ends in about 8 seconds. - Show the UI first. Call
figma.showUIbefore the license check, then update the window when the answer arrives. A plugin that waits for the network before opening looks hung. - Bundle your code. A plugin ships
code.jsandui.html. Use esbuild to produce them, including the token verifier from the offline page.
Doing this with Clavem
The License API needs no secret, so nothing sensitive ships in the plugin. Plan limits never block validation. See the API reference for every field.
Questions
Do I need to declare network access for a Figma plugin?
Yes. Figma's manifest has a networkAccess key with allowedDomains, and a plugin can only reach the domains it lists. Add the License API's origin, https://clavem.io, and test the plugin with the list in place.
Where should a Figma plugin keep a license key?
In figma.clientStorage, which Figma documents as storing data on the user's local machine, separately from the document and not synchronized across users. figma.root.setPluginData stores data in the file, where every collaborator can read it.
Why does the plugin need the currentuser permission?
figma.currentUser only works when manifest.json lists currentuser under permissions. The user's id is a stable value to hash into the fingerprint, so the same person on a second computer gets the same seat back.