Tiers & Features

Organize your licensing with pricing tiers (Free, Pro, Enterprise) and granular feature flags. Both are embedded in license JWT tokens for easy verification.

Tiers

Tiers represent different licensing levels. Common examples include Free, Pro, and Enterprise. Each license is associated with exactly one tier.

Tier Properties

Field	Type	Description
`name`	string	Display name (e.g., "Professional")
`slug`	string	Identifier used in JWT token (e.g., "pro")
`position`	integer	Sort order for display (lower = first)

Slug Format

Tier slugs must contain only lowercase letters, numbers, and underscores.

Valid: pro, enterprise, tier_1

Invalid: Pro, pro-tier, tier 1

Creating Tiers

POST /api/v1/apps/:slug/tiers

# Create multiple tiers
$ curl -X POST http://localhost:4000/api/v1/apps/my-app/tiers \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"name": "Free", "slug": "free", "position": 0}'

$ curl -X POST http://localhost:4000/api/v1/apps/my-app/tiers \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"name": "Professional", "slug": "pro", "position": 1}'

$ curl -X POST http://localhost:4000/api/v1/apps/my-app/tiers \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"name": "Enterprise", "slug": "enterprise", "position": 2}'

Features

Features are boolean flags that can be enabled per license. Use them for granular access control independent of tiers.

Feature Properties

Field	Type	Description
`name`	string	Display name (e.g., "API Access")
`slug`	string	Identifier used in JWT token (e.g., "api_access")
`description`	string?	Optional description

Creating Features

POST /api/v1/apps/:slug/features

$ curl -X POST http://localhost:4000/api/v1/apps/my-app/features \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "API Access",
    "slug": "api_access",
    "description": "Enables REST API access"
  }'

$ curl -X POST http://localhost:4000/api/v1/apps/my-app/features \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Priority Support",
    "slug": "priority_support",
    "description": "24/7 priority support channel"
  }'

In the License Token

When a license is issued, the tier slug and feature slugs are embedded in the JWT payload:

Decoded JWT payload

{
  "sub": "550e8400-e29b-41d4-a716-446655440000",
  "aud": "my-app",
  "iss": "license-server",
  "iat": 1706054400,
  "exp": 1737590400,
  "jti": "lic_abc123xyz",
  "lic_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "tier": "pro",
  "features": ["api_access", "priority_support"]
}

Updating Tier Features

When you add new features to a tier, existing licenses don't automatically receive them. Use license regeneration to update existing licenses with the new tier features.

Example: You add "webhooks" feature to the "pro" tier. Existing pro licenses can regenerate their tokens to receive the new feature, either via API key or by using their current license token for self-renewal.

Checking Tiers & Features

In your application code, check the tier and features to control access:

license_check.py

def check_api_access(license_payload):
    # Check by tier
    if license_payload["tier"] in ["pro", "enterprise"]:
        return True

    # Or check by specific feature
    if "api_access" in license_payload.get("features", []):
        return True

    return False

Apps Customers