> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flokitai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Entitlements API

> Check whether a user currently has an active entitlement.

<Note>
  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.
</Note>

Use the entitlement endpoints to gate premium features: after a purchase is verified (see the [Paywall API](/api-reference/paywall)), your app or backend can check whether the user's entitlement is active.

**Base URL:** `https://payments-gateway.flokitai.com`

Two paths return the same result:

* `GET /api/paywall/entitlement` — original path used by the paywall flow.
* `GET /api/entitlements/current` — canonical alias; also accepts a `userId` query parameter as an identity fallback.

Both require 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`](/api-reference/paywall#post-apipaywalltoken)) in `x-app-token` instead. The key scopes the request to your app and is safe to embed in your app build. `@flokit/subscriptions-sdk` v0.2.0+ sends it automatically via the `appKey` option.

Tenant resolution happens server-side from the app key and user identity — clients never send a company or tenant ID.

<Note>
  `x-app-key` enforcement is being phased in ahead of GA. Send it on every request today; once enforcement is on, requests without a valid key receive `401`.
</Note>

***

## GET /api/paywall/entitlement

### Headers

| Header      | Value                                 |
| ----------- | ------------------------------------- |
| `x-app-key` | Your publishable app key (required)   |
| `x-user-id` | Your authenticated user ID (required) |

### Example

<CodeGroup>
  ```bash cURL theme={null}
  curl https://payments-gateway.flokitai.com/api/paywall/entitlement \
    -H "x-app-key: pk_live_your_app_key" \
    -H "x-user-id: usr_abc123"
  ```

  ```typescript TypeScript theme={null}
  const res = await fetch(
    'https://payments-gateway.flokitai.com/api/paywall/entitlement',
    { 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
  }
  ```
</CodeGroup>

### Response

```json theme={null}
{
  "active": true,
  "source": "iap"
}
```

| Field    | Type    | Description                                          |
| -------- | ------- | ---------------------------------------------------- |
| `active` | boolean | Whether the user currently has an active entitlement |
| `source` | string  | Where the entitlement came from, e.g. `iap`          |

### Errors

| Status | Body                                    | Condition                                |
| ------ | --------------------------------------- | ---------------------------------------- |
| `401`  | `{ "error": "x-app-key is required." }` | Missing app key (once enforcement is on) |
| `401`  | `{ "error": "Invalid app key." }`       | Unknown or revoked app key               |
| `401`  | `{ "error": "x-user-id is required." }` | Missing user identity                    |

***

## GET /api/entitlements/current

Alias for the same entitlement check. Identity resolution order: `x-user-id` header, then `userId` query parameter.

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://payments-gateway.flokitai.com/api/entitlements/current?userId=usr_abc123" \
    -H "x-app-key: pk_live_your_app_key"
  ```

  ```typescript TypeScript theme={null}
  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();
  // { active: true, source: "iap" }
  ```
</CodeGroup>

Response and errors are identical to `GET /api/paywall/entitlement`.