Entitlements & Tiers

HiveForge's entitlement system controls what features, quotas, and capabilities each deployed application has access to. Entitlements are determined by the deployment's subscription tier and enforced at the API layer.

Core Concepts

Tiers

Every deployment is assigned one of five tiers that determine its capabilities:

See Tier Comparison for the full feature matrix.

Feature Flags

Boolean flags that gate access to platform capabilities:

• ai_enabled -- Access to the AI proxy (completions, embeddings)
• billing_enabled -- Access to the Stripe billing proxy
• custom_domain -- Ability to use a custom domain
• white_label -- Remove HiveForge branding
• mcp_enabled -- Access to MCP tool metering

See Feature Flags for details on checking each flag.

Quotas

Numeric limits that cap usage within a billing period:

• AI monthly limit -- Maximum AI tokens per month
• API rate limit -- Maximum API requests per minute

See Quotas & Limits for quota behavior and reset rules.

Credits

A fungible unit for metered usage across all proxy services:

• AI completions and embeddings
• Email sending
• Vector search and upsert
• Webhook delivery
• MCP tool calls

See Credit System for the full credit model.

Subscription Lifecycle

A deployment's subscription moves through these statuses:

┌─────────┐     ┌──────────┐     ┌────────┐
│ trialing │────►│  active   │────►│ canceled│
└─────────┘     └──────┬───┘     └────────┘
                       │
                       ▼
                ┌──────────┐     ┌───────────┐
                │ past_due  │────►│ suspended  │
                └──────┬───┘     └───────────┘
                       │
                       ▼
                ┌──────────────┐
                │ grace_period  │
                └──────────────┘

How Entitlements Are Checked

Every API request from a deployed application goes through the entitlement check:

1. Identify deployment -- Extract deployment ID from the request credentials
2. Load entitlements -- Fetch tier, features, quotas, and credit balance
3. Evaluate access -- Check the relevant feature flag and quota limits
4. Allow or deny -- Return the response or a structured error

The entitlement response includes a next_check_seconds field (default 300) that tells the client how long to cache the result before re-checking.

Quick Reference