Entitlements

Entitlements control what features and resources each organization can access. They combine global feature toggles (set by admins) with plan-based access rules to determine availability.

HasEntitlements Trait

The Organization model uses the HasEntitlements trait, which provides all entitlement-checking methods:

canAccess()

The primary check. Returns true only if the feature is both globally enabled by the admin and included in the organization's current plan:

if ($org->canAccess('api_keys')) {
    // Feature is globally enabled AND included in their plan
}

isFeatureVisible()

Checks only the global admin toggle, ignoring plan restrictions. Useful for showing or hiding UI elements regardless of plan:

if ($org->isFeatureVisible('webhooks')) {
    // Feature is turned on globally by the admin
}

planHasFeature()

Checks only plan inclusion, ignoring the global toggle. Useful for determining if an upgrade would grant access:

if ($org->planHasFeature('advanced_analytics')) {
    // The org's current plan includes this feature
}

Limits

Plans can define numeric limits for resources. The trait provides methods to check and query these limits:

getLimit()

Returns the numeric limit for a resource. Returns -1 for unlimited:

$maxKeys = $org->getLimit('api_keys');
// Returns: 5, 100, or -1 (unlimited)

isOverLimit()

Checks whether the current count exceeds the plan's limit:

if ($org->isOverLimit('members', $currentMemberCount)) {
    // Organization has exceeded its member limit
}

remaining()

Returns how many more of a resource can be created. Returns -1 for unlimited:

$left = $org->remaining('webhooks');
// Returns: 3 remaining, or -1 (unlimited)

Route Middleware

The CheckEntitlement middleware protects routes by verifying entitlements before the request reaches the controller:

Route::post('/api-keys', [ApiKeyController::class, 'store'])
    ->middleware('entitled:api_keys');

If the organization cannot access the feature, the middleware returns a 403 Forbidden response.

Entitlement API

The EntitlementController exposes the current organization's entitlements for the frontend to consume:

GET /api/entitlements

{
    "api_keys": {
        "visible": true,
        "plan_access": true,
        "limit": 10,
        "used": 3,
        "remaining": 7
    },
    "webhooks": {
        "visible": true,
        "plan_access": false,
        "limit": 0,
        "used": 0,
        "remaining": 0
    },
    "advanced_analytics": {
        "visible": false,
        "plan_access": false,
        "limit": null,
        "used": null,
        "remaining": null
    }
}

The frontend uses this data to show, hide, or disable features and display upgrade prompts.

Feature Configuration

Features are defined in two config files:

• config/saas.php — Core platform features (api_keys, webhooks, members, etc.)
• config/custom.php — Your application-specific features

Each feature entry defines its default visibility, limit behavior, and description. Admin settings can override the global toggle at runtime without redeploying.