Entitlements API

Endpoints for checking feature access, retrieving the entitlement manifest, and managing trials.

Get Entitlement Manifest

Returns the full list of features available for the authenticated user's subscription tier.

GET /v1/entitlements/manifest
Authorization: Bearer <jwt>

Response: 200 OK

{
  "data": {
    "tier": "pro",
    "features": [
      "encrypted_sync",
      "skills_hub_publish",
      "skills_hub_private",
      "cloud_model_brokering",
      "priority_support",
      "premium_themes",
      "premium_addons"
    ],
    "quotas": {
      "sync_storage_bytes": 104857600,
      "skills_publish_limit": 50,
      "rate_limit_per_minute": 300
    }
  }
}

TIP

Clients should cache the entitlement manifest with a 5-minute TTL to reduce API calls while staying responsive to tier changes.

Feature Map by Tier

Feature	Core	Pro	Studio
core_tools	✅	✅	✅
swarm_mode	✅	✅	✅
skills_local	✅	✅	✅
mcp_support	✅	✅	✅
plugins	✅	✅	✅
checkpoints	✅	✅	✅
memory	✅	✅	✅
byom	✅	✅	✅
encrypted_sync	—	✅	✅
skills_hub_publish	—	✅	✅
skills_hub_private	—	✅	✅
cloud_model_brokering	—	✅	✅
priority_support	—	✅	✅
premium_themes	—	✅	✅
premium_addons	—	✅	✅
team_profiles	—	—	✅
shared_memory	—	—	✅
sso	—	—	✅
audit_log	—	—	✅
private_mcp_servers	—	—	✅
rbac	—	—	✅
priority_cloud_brokering	—	—	✅
dedicated_support	—	—	✅
skills_hub_org	—	—	✅

Check Feature Access

Check if the authenticated user has access to a specific feature.

GET /v1/entitlements/check/:feature
Authorization: Bearer <jwt>

Response: 200 OK

{
  "data": {
    "feature": "encrypted_sync",
    "allowed": true,
    "required_tier": "pro"
  }
}

When allowed is false, the required_tier field indicates the minimum tier needed. Clients should display an upgrade prompt directing to nexus-suite.dev/pricing.

Get Trial Status

GET /v1/entitlements/trial
Authorization: Bearer <jwt>

Response: 200 OK

{
  "data": {
    "eligible": true,
    "active": false,
    "trial_start": null,
    "trial_end": null,
    "days_remaining": null
  }
}

When a trial is active:

{
  "data": {
    "eligible": false,
    "active": true,
    "trial_start": "2024-01-15T00:00:00Z",
    "trial_end": "2024-01-29T00:00:00Z",
    "days_remaining": 10
  }
}

Start Trial

Start a 14-day Pro trial. Each account is eligible for one trial. No payment information required.

POST /v1/entitlements/trial/start
Authorization: Bearer <jwt>

Response: 200 OK

{
  "data": {
    "tier": "pro",
    "trial_start": "2024-01-15T00:00:00Z",
    "trial_end": "2024-01-29T00:00:00Z"
  }
}

Errors:

Code	Condition
FORBIDDEN	User has already used their trial (trial_eligible = false)

INFO

During the trial, the user has full access to all Pro tier features. When the trial expires without a subscription, entitlements revert to the Core tier automatically.