Entitlements API

These endpoints are live in production today, served by the FloKit payments gateway. They are separate from the v1 REST API, which is still in design-partner preview.

Use the entitlement endpoints to gate premium features: after a purchase is verified (see the Paywall API), your app or backend can check whether the user’s entitlement is active. Entitlement state is authoritative only after a verified source updates it: StoreKit/Google receipt verification, provider import/live-read, or a provider webhook that has passed readiness gates. A Paddle browser redirect alone never grants access. Base URL: https://payments-gateway.flokitai.com GET /api/entitlements/current is the single entitlement endpoint. It requires your app’s publishable key (pk_..., created per app in the FloKit dashboard) in the x-app-key header — or a short-lived app-session token (minted via POST /api/paywall/token) in x-app-token instead. The key scopes the request to your app and is safe to embed in your app build. @flokitai/subscriptions-sdk v2.0+ sends it automatically — set appKey in initSubscriptionsSdk() and reads carry x-app-key (or x-app-token) for you. Tenant resolution happens server-side from the app key and user identity — clients never send a company or tenant ID.

x-app-key enforcement is on in production. Requests without a valid app credential receive 401 — there is no grace period.

Migrating from the paywall path. GET /api/paywall/entitlement was removed — it now 404s. Read entitlements from GET /api/entitlements/current instead. The response field product_id was renamed to entitlement_key.

GET /api/entitlements/current

Returns the caller’s current entitlement state.

Headers

Header	Value
`x-app-key`	Your publishable app key (required — or `x-app-token`)
`x-user-id`	Your authenticated user ID (required unless supplied as a query parameter)

Query parameters

string

User identity fallback if the x-user-id header is not set.

string

Anonymous identity fallback for pre-login users.

Identity resolution order: x-user-id header, then the userId query parameter, then anonymousId.

Example

curl "https://payments-gateway.flokitai.com/api/entitlements/current?userId=usr_abc123" \
  -H "x-app-key: pk_live_your_app_key"

const res = await fetch(
  'https://payments-gateway.flokitai.com/api/entitlements/current',
  { headers: { 'x-app-key': 'pk_live_your_app_key', 'x-user-id': 'usr_abc123' } },
);

const entitlement = await res.json();
if (entitlement.active) {
  // unlock premium features
}

Response

{
  "active": true,
  "entitlement_key": "pro_monthly",
  "expires_at": "2026-09-01T00:00:00.000Z",
  "provider": "apple",
  "state": "active",
  "source_event_id": "evt_01j...",
  "updated_at": "2026-08-01T12:00:00.000Z",
  "source": "entitlement"
}

Field	Type	Description
`active`	boolean	Whether the user currently has an active entitlement
`entitlement_key`	string	Opaque entitlement identifier — the store product id for native purchases, the Package key for web. Renamed from `product_id`. Treat it as opaque: do not parse it
`expires_at`	string \| null	ISO 8601 expiry. `null` means open-ended
`provider`	string	One of `apple`, `google`, `paddle`, `lemon_squeezy`, `stripe_direct`, `stripe_managed_payments`, `custom`
`state`	string	One of `trialing`, `active`, `grace`, `paused`, `canceled_paid_through`, `expired`, `refunded`, `revoked`
`source_event_id`	string	The provider event that last wrote this entitlement
`updated_at`	string	ISO 8601 timestamp of the last write
`source`	string	One of `entitlement`, `provider_verified`, `none`

When there is no entitlement, the response carries only active: false and source:

{
  "active": false,
  "source": "none"
}

Paddle entitlements are exposed here only after Paddle webhook and canonical entitlement projection are both ready for the app/environment.

Errors

Status	Body	Condition
`401`	`{ "error": "x-app-key is required." }`	Missing app key (when app-key enforcement is on)
`401`	`{ "error": "Invalid app key." }`	Unknown or revoked app key
`401`	`{ "error": "Invalid app token." }`	Expired or malformed `x-app-token`
`401`	`{ "error": "App token origin mismatch." }`	App token presented for a different app or user
`401`	`{ "error": "x-user-id header or userId query param is required." }`	Missing user identity

Live endpoints

API reference

GET /api/entitlements/current

Headers

Query parameters

Example

Response

Errors

​GET /api/entitlements/current

​Headers

​Query parameters

​Example

​Response

​Errors

GET /api/entitlements/current

Headers

Query parameters

Example

Response

Errors