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

# The Entitlement object

> Data model and reference for resolved feature entitlements, usage limits, allocations, and rule evaluations.

The entitlement and feature-flag APIs are how your backend makes authoritative access decisions. Two read endpoints (`/check`, `/entitlements`) resolve a company's access, `/usage/consume` decrements metered quota, and the `/flags/check` alias covers single-flag reads. Creating feature flags and rules happens in the dashboard — your code only consumes the resolved result.

## Check a single feature

`GET /api/v1/check?key=<featureKey>` resolves one feature for a company.

Auth (either):

* API key (`api_…`, `sk_…`, `pk_…`, `rk_…`)
* Embed access token

### Query parameters

<ParamField query="key" type="string" required>
  The feature key (feature flag key or entitlement key) to evaluate. Maximum 128 characters.
</ParamField>

### Company/user resolution

With an API key, pass the company identity via headers:

```
X-Arcen-Company-Keys: id=company_123,wallet=0xabc...
X-Arcen-User-Keys: id=user_123,wallet=0xabc...
```

At least one company key (`id`, `wallet`, or `email`) is required.

With an embed access token, the company and user are resolved from the token — no headers needed.

### Response

```json theme={null}
{
  "key": "analytics_export",
  "enabled": true,
  "reason": "PLAN_ALLOWS",
  "allocation": 100,
  "usage": 34,
  "exceeded": false
}
```

| Field        | Type           | Description                                                   |
| ------------ | -------------- | ------------------------------------------------------------- |
| `key`        | string         | Feature key                                                   |
| `enabled`    | boolean        | Whether the company currently has access                      |
| `reason`     | string         | Resolution reason (e.g. `PLAN_ALLOWS`, `OVERRIDE`, `NO_PLAN`) |
| `allocation` | number \| null | Total allowed units for numeric features                      |
| `usage`      | number \| null | Units consumed so far                                         |
| `exceeded`   | boolean        | `true` when usage is at or above allocation                   |

`GET /api/v1/flags/check?key=...` is an alias for this endpoint.

## Bulk entitlements

`GET /api/v1/entitlements` resolves every feature flag and entitlement for a company in a single request.

Same auth options as `/check`. With an API key, `X-Arcen-Company-Keys` is required (at least one of `id`, `wallet`, or `email`).

### Response

```json theme={null}
{
  "entitlements": [
    {
      "key": "analytics_export",
      "enabled": true,
      "reason": "PLAN_ALLOWS",
      "allocation": 100,
      "usage": 34,
      "exceeded": false
    },
    {
      "key": "api_calls_limit",
      "enabled": true,
      "reason": "PLAN_ALLOWS",
      "allocation": 1000,
      "usage": 412,
      "exceeded": false
    }
  ]
}
```

The React SDK hook `useCompanyEntitlements` calls this endpoint; the Node SDK wraps it as `client.listEntitlements()`.

## Consume metered usage

`POST /api/v1/usage/consume` atomically checks a metered entitlement, burns credits if configured, and increments usage.

Auth: API key (`api_…`, `sk_…`, `rk_…`, `pk_…`) or embed access token.

### Request body

<ParamField body="featureKey" type="string" required>
  The feature key to consume against. Maximum 128 characters.
</ParamField>

<ParamField body="traits" type="object">
  Attributes recorded with the consumption.
</ParamField>

<ParamField body="idempotencyKey" type="string">
  Unique key for the logical operation. Maximum 128 characters. Prevents double-charging on retries.
</ParamField>

### Example

```bash theme={null}
curl -X POST https://api.arcenpay.com/api/v1/usage/consume \
  -H "Authorization: Bearer sk_live_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "X-Arcen-Company-Keys: id=company_123" \
  -d '{ "featureKey": "scan", "idempotencyKey": "scan-req-1" }'
```

### Response

```json theme={null}
{
  "consumed": true,
  "featureKey": "scan",
  "remaining": 66
}
```

On failure the request returns `403` (feature disabled or tier restriction), `402` (insufficient credits), or `429` (limit reached) with an error message.

<Note>
  Usage metering and credit consumption require a paid platform tier (Growth/Plus or Enterprise/Pro). Free-tier teams receive `UPGRADE_REQUIRED` (`403`).
</Note>

## Managing feature flags is dashboard-only

Creating feature flags, rules, overrides, and feature definitions happens **in the dashboard's Features section** — there is no SDK method and no API-key access to those management endpoints. The dashboard calls `/api/v1/feature-flags`, `/features`, and related routes with a session cookie and role-based permissions (`catalog:read` / `catalog:write`).

As an integrating developer you only **consume** the resolved access state via the endpoints above. If you need to force a flag for one customer, the Node SDK exposes `setCompanyOverride()` (backed by `POST /api/v1/companies/:id/overrides` with a legacy `api_…` key).

<Note>
  The `POST /api/v1/companies/:id/overrides` endpoint accepts legacy `api_…` keys or a dashboard session. See the [endpoint auth matrix](/api/authentication#which-key-works-where--the-endpoint-auth-matrix).
</Note>

## Related

* [Checking access with the Node SDK](/sdk/node/access-checks)
* [Feature gating guide](/guides/feature-gating)
* [Entitlements concept](/concepts/entitlements)