BranchPy
Log in

Docs-Builder

# Licensing & Entitlements

Version: 1.1.1
Last Updated: January 23, 2026

Plans & Tiers

Plan Who it’s for Duration Renewal Highlights
Unregistered First-time users N/A N/A Basic analyze/stats/help/logs
Free (Registered) Logged-in users Unlimited N/A Full analysis core, doctor lite, compare
Ren’Py Free Ren’Py developers 30 days Manual, free forever All features (47+), renewable; honor system + optional evidence
Pro Solo commercial 30 days Auto AI, pilot, PFI, patch, cloud solo
Team Teams 30 days Auto Collaboration, team cloud, identity, audit, policy
Enterprise Large studios Custom Auto SSO, priority support, VPC, custom integrations

Feature Highlights (abridged)

  • Advanced: pilot_mode, pfi, patch, doctor_full
  • AI: ai_review, ai_docgen, ai_explain, ai_patch, ai_bqf
  • Cloud/Team: cloud_sync, team_cloud, identity, audit, policy, telemetry
  • Enterprise: sso, priority_support, custom_integrations, vpc_cloud

Entitlement Accessors (Python API)

From deferred extract (rehomed here):

from branchpy.license import (
    login, logout, refresh_token, load_entitlements,
    has_feature, require_feature, get_plan,
    FeatureNotEntitledError,
)
  • has_feature(feature_key) → bool gate
  • require_feature(feature_key, label) → decorator/guard
  • get_plan() → current plan code
  • Entitlements cached in ~/.branchpy/auth.json (license token + refresh token)

Claim & Renewal

  • Ren’Py Claim: branchpy license claim-renpy → POST /v1/claim/renpy (idempotent, always 200). Returns fresh license_token, sets plan renpy_free, updates website_users.
  • Ren’Py Renewal: 30-day cycle with grace prompts; CLI/extension prompt 3 days before expiry; renewal reissues token.
  • Paid Plans: Issued via website checkout + webhooks; token expiry aligns with billing period.

Entitlement Decision Points

  • Client gating via has_feature/require_feature before invoking advanced features.
  • API-side checks on license endpoints ensure plan/feature coverage.
  • UI gating should grey/lock features when absent; see INTEGRATION_GUIDE.md patterns.

Feature Matrix Source

  • Canonical mapping: docs/v1.1.0/licensing/ENTITLEMENTS_MAPPING_v2.md (full table).
  • Quick lookup: quick-reference.md in this folder.

License Token Structure (Entitlements JWT)

  • Claims: sub, plan, features[], exp, iat, max_offline_days, iss=branchpy-auth, aud=branchpy-app.
  • Signature: RS256; verified offline via embedded public key.
  • Storage: ~/.branchpy/auth.json (license_token, refresh_token, device_id, last_online).
  • Offline: Valid until exp and within max_offline_days since last_online.

Access & Refresh Tokens

  • Access: 15 minutes, memory only, used for API calls.
  • Refresh: 30–90 days, on disk, POST /v1/auth/refresh.
  • Governance events: auth.login_*, auth.refresh_*, auth.logout, auth.token_revoked.

Database Touchpoints

  • users (legacy CLI) and website_users (canonical). Email unique enforced via Migration 024.
  • subscriptions stores plan and renewal dates.
  • plan_features maps plan → feature keys (server-side gate source).
  • licenses stores issued license tokens and renewal counters.
  • renpy_licenses tracks claims/renewals (idempotent endpoint uses this).

Governance Events (Implemented Now)

  • auth.login_success|failed, auth.refresh_success|failed, auth.logout, auth.token_revoked
  • license.entitlement_check, license.claim
  • installation.device_approved (device flow)

Source References (rehomed)

  • _migration/deferred-content/api-extracts/auth-licensing.md (Python API accessors, plan queries, feature key table)
  • licensing/License_Architecture_v1.0_CANONICAL.md
  • licensing/ENTITLEMENTS_MAPPING_v2.md
  • licensing/QUICK_REFERENCE.md
  • licensing/CLAIM_ENDPOINT_IMPLEMENTATION.md