Plan Capabilities and Entitlements
Entitlements are the access and limit controls produced by Billing (PBM). When a tenant or customer subscribes to a plan, the subscription determines both what is billed and what the subscriber can use.
Every billable plan capability is either a feature toggle, such as whether biometric checks are available, or a numeric limit, such as how many active application instances can be created.
The three-layer model
Billing-derived capabilities are resolved at three layers. All applicable layers must allow an operation before it can proceed.
Layer 1 — Platform plan limits
Every tenant is also a customer of Raytio. The subscription that tenant holds as a Raytio customer determines the platform limits, which set the maximum capabilities available to the tenant.
- Platform limits are read-only from the tenant's perspective. Tenant administrators cannot edit or override them.
- They are updated automatically whenever the corresponding Raytio subscription changes.
- For numeric limits, the platform value acts as a hard cap: if the platform grants a maximum of 50 team members, the tenant cannot configure a higher value.
- For boolean features, the platform value acts as a gate: if the platform disables a feature, the tenant cannot enable it.
When no platform limit exists for a feature, there is no ceiling at this layer.
Layer 2 — Tenant capabilities
Tenant capabilities represent what the tenant's own subscriptions and approved overrides allow.
- Tenant capabilities cannot exceed the platform ceiling. The platform limit always takes priority.
- For numeric limits, the effective value is the lower of the platform limit and the tenant limit.
- For boolean features, the feature must be enabled at both the platform and tenant level.
All existing features default to tenant-level enforcement only.
Layer 3 — Customer capabilities
Within a tenant, each customer can have its own subscriptions that determine what that customer can use. Customer capabilities add a per-customer dimension to billing plans.
- Customer capabilities are resolved from the customer's subscriptions within the tenant, plus any customer-level overrides.
- They are enforced independently from tenant capabilities — both must pass when both layers apply.
- The active customer for a request is determined automatically based on the user's session.
When no customer-specific value exists for a feature, the platform uses the feature's default value.
Enforcement scope
Each feature in the platform catalogue declares an enforcement scope that controls which layers are checked:
| Scope | Meaning | Example |
|---|---|---|
| Tenant only | Only tenant-level (and platform ceiling) checks apply. No customer check. | Tenant-wide settings like maximum users across the whole tenant. |
| Customer only | Only customer-level checks apply. No tenant check. | Features that only make sense per-customer. |
| Both | Both tenant-level and customer-level checks apply. All must pass. | Quota limits like maximum active application instances, where both the tenant and the customer have independent caps. |
All existing features default to TENANT_ONLY, preserving the behaviour from before customer entitlements were introduced. New features choose the appropriate scope when they are added to the catalogue.
How enforcement works
Plan capabilities are enforced automatically on relevant operations. For a feature scoped as both, independent checks run for the tenant layer and the customer layer. Both must pass for the operation to succeed.
How each type is evaluated:
- Boolean features: the feature must be enabled at the platform level, the tenant level, and (if applicable) the customer level. All must be true.
- Numeric limits (quotas): the current count must be below the effective limit at the tenant level and (if applicable) below the customer's limit. Both must pass.
Customer context
The system determines which customer a request applies to automatically:
- Explicit selection — the user selects or specifies a customer in the request.
- Default customer — if no selection is made, the user's configured default customer is used.
- Automatic selection — if no default is set, the system selects a customer the user has access to.
If the user has no customer association at all, features with customer-level enforcement will deny the request.
Relationship to authorisation
Billing entitlements and authorisation are independent checks that are both applied:
- Authorisation answers: "Does this user have permission to perform this action?" (role-based)
- Entitlements answer: "Is this action allowed by the tenant's and customer's subscription?" (subscription-based)
A user needs both the right role permissions and sufficient entitlements for an operation to succeed. Neither alone is sufficient.
Feature catalogue
All features controlled by Billing (PBM) are defined in a central feature catalogue. Each feature has:
- A unique feature code (e.g. "maximum active application instances", "biometric checks enabled")
- A value type (boolean or integer)
- A default value (used when no entitlement exists)
- An enforcement scope (tenant only, customer only, or both)
The catalogue is the single source of truth for what features exist and how they are enforced.