Licensing & desktop handshake

The Forven desktop app verifies your subscription by calling the Forven entitlement API. This page describes how that handshake works — useful if you're integrating a custom build, debugging license issues, or curious about what the app sends.

Overview

Each user can link one or more devices from /account. Linking issues a refresh token — an opaque bearer string that authenticates a single installation. The desktop app stores the token in the OS keychain and calls GET /api/entitlement periodically to refresh its license state.

Endpoints

POST /api/devices/register

Auth: web session cookie (Auth.js). Body: { "name": "Desktop" } (optional, max 80 chars). Response:

{
  "deviceId": "uuid",
  "refreshToken": "fv_…",
  "name": "Desktop"
}

The token is shown once and never returned again. Desktop pastes it in during setup; the web UI warns you to copy it immediately.

GET /api/entitlement

Auth: Authorization: Bearer <refreshToken>. Response:

{
  "tier": "forged" | "free",
  "status": "active",
  "currentPeriodEnd": "2026-05-21T00:00:00.000Z" | null,
  "deviceId": "uuid",
  "offlineGraceHours": 72,
  "checkedAt": "2026-04-21T15:30:00.000Z"
}

tier is the only field the desktop needs for the unlock gate:

• forged — full features unlocked.
• free — gated to the free tier.

GET /api/devices

List your linked devices.

DELETE /api/devices?id=<uuid>

Revoke a device. The desktop will fail its next entitlement check and drop back to free tier after the grace window expires.

Offline grace period

The desktop caches the last successful /api/entitlement response to disk. If it can't reach the server — bad Wi-Fi, travel, server outage — it keeps honoring the cached tier for offlineGraceHours (72 hours by default) past checkedAt. After that window expires, the app falls back to free tier until it can reach the server again.

This is a pragmatic tradeoff: users don't get locked out of their own research if we're down, and we don't need to ship a long-lived offline license file.

Security notes

• Refresh tokens are long random strings stored in the DB and compared directly. Rotate by revoking and re-linking.
• The token is the only credential needed to call /api/entitlement — treat it like a password.
• Web session cookies cannot be used to call /api/entitlement; that endpoint accepts only bearer tokens. This keeps browser origins from being able to mint entitlement responses indirectly.