Entitlements

Entitlements represent features or capabilities that can be attached to policies and licenses. Use them for feature gating within your application.

Create Entitlement

POST/entitlements

Create a new entitlement. Requires API Key auth with entitlements:write scope.

Request Body

Parameter	Type	Required	Description
code	string	Required	Unique entitlement code (1-100 chars, lowercase alphanumeric, hyphens, underscores)
name	string	Required	Human-readable entitlement name (1-255 characters)
metadata	object	Optional	Arbitrary key-value metadata

Request

{
  "code": "feature_export",
  "name": "Export Feature",
  "metadata": { "tier": "pro" }
}

201Entitlement created

json

{
  "data": {
    "id": "a1b2c3d4-1111-2222-3333-444455556666",
    "code": "feature_export",
    "name": "Export Feature",
    "accountId": "a0b1c2d3-7f15-8192-d356-ce0f1a2b3c4d",
    "createdAt": "2026-01-08T12:00:00.000Z",
    "updatedAt": "2026-01-08T12:00:00.000Z",
    "deletedAt": null,
    "metadata": {}
  }
}

List Entitlements

GET/entitlements

List all entitlements with cursor-based pagination. Requires API Key auth with entitlements:read scope.

Query Parameters

Parameter	Type	Required	Description
cursor	uuid	Optional	Pagination cursor from previous response
limit	integer	Optional	Results per page (1-100, default 25)

Request

GET /api/v1/entitlements?limit=50

200Paginated list

json

{
  "data": [
    {
      "id": "a1b2c3d4-1111-2222-3333-444455556666",
      "code": "feature_export",
      "name": "Export Feature",
      "createdAt": "2026-01-08T12:00:00.000Z",
      "updatedAt": "2026-01-08T12:00:00.000Z",
      "deletedAt": null,
      "metadata": {}
    },
    {
      "id": "b2c3d4e5-2222-3333-4444-555566667777",
      "code": "feature_analytics",
      "name": "Analytics Dashboard",
      "createdAt": "2026-01-09T08:00:00.000Z",
      "updatedAt": "2026-01-09T08:00:00.000Z",
      "deletedAt": null,
      "metadata": {}
    }
  ],
  "pagination": {
    "nextCursor": "b2c3d4e5-2222-3333-4444-555566667777",
    "hasMore": false
  }
}

How Entitlements Work

Attach to Policies

Pass entitlementIds when creating a policy. All licenses under that policy automatically inherit those entitlements.

Attach to Licenses

Pass entitlementIds when creating a license to add entitlements on top of what the policy provides.

Check During Validation

Pass entitlements in the validation request body to verify the license has specific features. Missing entitlements return ENTITLEMENTS_MISSING.

Naming Convention

Use lowercase codes with underscores for entitlements (e.g., feature_export, max_users_100). This makes them easy to reference in application code.

Policies Webhooks