Where the key and the state live
Raycast gives an extension two places for secrets. A preference of type password holds what the user types, and the storage API holds what the extension writes. Raycast’s security page says both go into its local encrypted database and only the extension that wrote them can read them.
"preferences": [
{
"name": "licenseKey",
"type": "password",
"required": false,
"title": "License key",
"placeholder": "XXXXX-XXXXX-XXXXX-XXXXX-XXXXX",
"description": "From your purchase email. Leave empty to use the free features."
}
]
Use LocalStorage for the instance id and the token, as strings, because it takes strings, numbers and booleans. Do not use Cache for them: the Cache docs describe a least-recently-used cache, which is the wrong home for a token you cannot rebuild while offline.
Check on every command
isLicensed and verifyToken come from the offline verification guide. The extension activates when the preference holds a key it has not activated yet, and validates otherwise.
import { LocalStorage, getPreferenceValues } from '@raycast/api';
import { hostname } from 'node:os';
import { isLicensed, verifyToken } from './token';
const BASE = 'https://clavem.io';
const DAY = 24 * 60 * 60 * 1000;
export type LicenseState = 'licensed' | 'invalid' | 'needs-network' | 'unlicensed';
interface Saved { key: string; instanceId: string; token: string; checkedAt: number }
async function call(action: string, body: Record<string, string>) {
const res = await fetch(`${BASE}/v1/licenses/${action}`, {
method: 'POST',
headers: { 'content-type': 'application/json' },
body: JSON.stringify(body),
signal: AbortSignal.timeout(5000),
});
return { status: res.status, json: (await res.json().catch(() => ({}))) as any };
}
async function load(): Promise<Saved | null> {
try {
const raw = await LocalStorage.getItem<string>('license');
return raw ? (JSON.parse(raw) as Saved) : null;
} catch {
return null;
}
}
const save = (saved: Saved | null) =>
saved ? LocalStorage.setItem('license', JSON.stringify(saved)) : LocalStorage.removeItem('license');
/** Call it at the top of every command that needs a license. */
export async function checkLicense(): Promise<LicenseState> {
const key = getPreferenceValues<{ licenseKey?: string }>().licenseKey?.trim();
if (!key) return 'unlicensed';
let saved = await load();
if (saved && saved.key !== key) saved = null; // the owner pasted a different key: activate again
// Commands start on every hotkey press. Trust a fresh token for a day instead of calling the API each time.
if (saved && Date.now() - saved.checkedAt < DAY && isLicensed(verifyToken(saved.token))) return 'licensed';
try {
if (!saved) {
const { status, json } = await call('activate', { license_key: key, instance_name: hostname() });
if (json.activated) {
await save({ key, instanceId: json.instance.id, token: json.token, checkedAt: Date.now() });
return 'licensed';
}
return status === 429 || status >= 500 ? 'needs-network' : 'invalid'; // json.error says why
}
const { status, json } = await call('validate', { license_key: key, instance_id: saved.instanceId });
if (status === 200) {
// Keep the new token even when the license is not valid: offline, it then says so.
await save({ ...saved, token: json.token, checkedAt: Date.now() });
return json.valid ? 'licensed' : 'invalid';
}
if (status === 404) {
await save(null); // unknown key, or this Mac was removed: the next run activates again
return 'invalid';
}
} catch {
// No network, or no answer in 5 seconds.
}
// Offline, rate limited (429) or the service is down (503): trust the stored token while it is fresh.
return saved && isLicensed(verifyToken(saved.token)) ? 'licensed' : 'needs-network';
}
Why once a day
Validating at every launch is the general advice. A Raycast command is not a launch of an app: a user may run a command twenty times before lunch. With the daily cache they cause one validate call, not twenty, and the other nineteen open as fast as a local check. The cost is that a revocation reaches this Mac up to a day later, well inside the 14-day life of a token.
Outcomes
| Answer | State | Next |
|---|---|---|
activate returns activated: true |
licensed | state saved |
| activate refused (404, or 400 for limit, expiry or a disabled key) | invalid | json.error has the message to show |
validate 200, valid: true |
licensed | token replaced, daily timer restarts |
validate 200, valid: false |
invalid | token replaced, key kept |
| validate 404 | invalid | state cleared, next run activates again |
| 429, 503 or no network | stored token decides | asks again on the next command after the day is up |
Raycast traps
- Background commands. A
no-viewor menu bar command can launch on an interval, with a minimum of 10 seconds, and Raycast ends it when it runs too long. Five seconds of network timeout leaves room. Because of the daily cache, scheduled launches do not call the API more than user launches do. - No hardware id. The code sends no
fingerprint. Reinstalling the extension clears LocalStorage, and the next run activates again on another seat until the old one is removed. Hashing the host name would be stable, but two Macs with the same name would share a seat. - Open source. Store extensions are public and MIT licensed, so a buyer can read this code and edit it. I could not find Raycast’s rules for paid extensions in its developer docs, so read the Extension Guidelines before you build a business on a Store listing.
- How I tested it. I ran this code against a stub of the Raycast API in Node. It passed against a local mock for each row of the table above, and against the demo key on the live API, where an unknown instance returned 404 and cleared the state. It has not run inside Raycast.
Doing this with Clavem
The key is the credential, so the extension carries no secret. Clavem’s API reference describes the activate and validate answers that the table above is built from.
Questions
Is a license check in a Raycast Store extension secure?
Raycast publishes every extension's source in its public repository and requires an MIT license in package.json, so anyone can read and edit the check. It stops casual sharing. It is stronger when the key gates something your own server does, because your server can run the check.
What happens when the user changes the key in preferences?
The saved key no longer matches, so the extension activates again with the new one. The old seat stays used until its owner removes it on the device page at clavem.io/licenses/manage.
Sources
- Raycast developer docs, security (extensions are open source; password preferences and LocalStorage in the encrypted database; checked November 2026)
- Raycast developer docs, storage (checked November 2026)
- Raycast developer docs, cache (checked November 2026)
- Raycast developer docs, background refresh (checked November 2026)
- Raycast developer docs, prepare an extension for the Store (MIT license field; checked November 2026)