Skip to main content

Entitlement Tokens

Entitlement tokens are short-lived, signed JWTs that carry tier limits and feature grants. They are the only source of truth for client-side tier enforcement.

How tokens are issued​

  • POST /api/license/verify validates the publishable or secret key plus domain rules.
  • The server signs a token (ES256) bound to projectId and host.
  • Tokens expire (default: 1 hour) and are re-verified before use.

How to obtain a token (browser)​

Use the licensing client (recommended):

import { initRowOpsClient } from "@rowops/licensing";

const { entitlementToken } = await initRowOpsClient({
  projectId: "proj_123",
  publishableKey: "pk_live_...",
});

if (!entitlementToken) {
  // Verification failed => Free tier only
}

If you need to proxy the verification request, call the control plane endpoint from your backend or directly from the browser:

const res = await fetch("https://api.rowops.dev/api/license/verify", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-RowOps-Publishable-Key": "pk_live_...",
  },
  body: JSON.stringify({
    projectId: "proj_123",
    ts: Date.now(),
  }),
});

const { entitlementToken } = await res.json();

Publishable keys are safe for browser usage. Secret keys must stay server-side.

Note: For publishable keys, origin is derived from HTTP headers (Origin/Referer/Host). The body.origin field is ignored for browser requests and is only used for headless secret-key flows.

How to use the token​

Pass the signed token into resolveBrowserLicense to create a tierGateInit:

import { resolveBrowserLicense } from "@rowops/import-core";

const { tierGateInit } = await resolveBrowserLicense({
  projectId: "proj_123",
  entitlementToken,
});

// Pass tierGateInit into gated modules or ImportJob creation.

Security model​

  • Clients cannot mint or upgrade tokens; only server-signed tokens are accepted.
  • Verification failure (missing, invalid, expired, wrong host) fails closed to Free.
  • Tokens are not secrets, but treat them as bearer credentials.
  • Avoid hardcoding tokens; fetch them per session and protect against XSS.
  • The WASM tier gate re-validates tokens at pipeline start and worker boundaries.

FAQ​

Does the end user need to fetch the token?​

Your app must fetch it at runtime (browser or backend). The token is bound to the current project and host and is short-lived.

Is it safe to pass the token in client code?​

Yes. The token is signed and verified locally, and the WASM tier gate enforces limits. An attacker can only use a valid token on the same host until it expires.