Entitlements API¶

Base: /api/organizations/{organization_id}/subscribers/{subscriber_id}/entitlements

Hot path for product gating. Same auth as the rest of the API: member API key (X-API-Key).

Check feature¶

POST /api/organizations/{organization_id}/subscribers/{subscriber_id}/entitlements/check

{
  "feature": "sso"
}

Field	Required	Rules
`feature`	yes	Feature key string

200 — always when subscriber exists (even if not entitled)

Flag

{
  "feature": "sso",
  "kind": "flag",
  "allowed": true,
  "source": "plan"
}

Limit

{
  "feature": "seats",
  "kind": "limit",
  "limit": 10,
  "source": "plan"
}

Unlimited:

{
  "feature": "seats",
  "kind": "limit",
  "limit": null,
  "source": "override"
}

Not entitled (no grant):

{
  "feature": "seats",
  "kind": "limit",
  "limit": 0,
  "source": "none"
}

Field	Meaning
`kind`	`flag` or `limit` (from catalog)
`allowed`	Flag only
`limit`	Limit only: integer ≥ 0, or `null` = unlimited
`source`	`override` \| `plan` \| `none`

Note

For flags: deny via override → allowed: false, source: override.
Deny with no override/plan → allowed: false, source: none.
For limits: missing grant → limit: 0, source: none. Explicit plan limit: 0 → source: plan.

404 — subscriber not found

422 — missing/invalid body, or feature is not a key in your catalog

List entitlements¶

GET /api/organizations/{organization_id}/subscribers/{subscriber_id}/entitlements

By default, returns only features that are entitled:

flag with allowed: true
limit with limit === null or limit > 0

Pass ?all=true to include every catalog feature with full effective values.

200 (default)

{
  "features": [
    {
      "feature": "sso",
      "kind": "flag",
      "allowed": true,
      "source": "plan"
    },
    {
      "feature": "seats",
      "kind": "limit",
      "limit": 10,
      "source": "plan"
    }
  ]
}

404 — subscriber not found