License Regeneration

When to Regenerate

• Tier features updated - When you add new features to a tier
• Key rotation - After rotating RSA keys, licenses need new tokens
• Feature sync - Ensure licenses have the latest feature set
• Self-renewal - Allow customers to refresh their own tokens

How It Works

When you regenerate a license token, Blackwalnut:

1. Fetches the current feature set from the license's tier
2. Merges tier features with any per-license custom features
3. Generates a new JWT token with the updated features
4. Preserves original installation_id, customer_id, tier, and expiration
5. Updates the token's jti (JWT ID) and iat (issued at) claims

Authentication Methods

The regenerate endpoint supports two authentication methods:

$ curl -X POST /api/v1/apps/my-app/licenses/lic_abc123/regenerate \
  -H "Authorization: Bearer sk_live_your_api_key"

$ curl -X POST /api/v1/apps/my-app/licenses/lic_abc123/regenerate \
  -H "Content-Type: application/json" \
  -d '{"current_token": "eyJhbGciOiJSUzI1NiIs..."}''

Use Case: Feature Updates

When you add a new feature to a tier, existing licenses don't automatically receive it. Use regeneration to update licenses with the new feature:

# 1. Original license has tier "pro" with features: ["api_access"]

# 2. You add "webhooks" feature to the "pro" tier
$ curl -X POST /api/v1/apps/my-app/tiers/pro/features \
  -H "Authorization: Bearer sk_live_..." \
  -d '{"name": "Webhooks", "slug": "webhooks"}'

# 3. Regenerate the license to get updated features
$ curl -X POST /api/v1/apps/my-app/licenses/lic_abc123/regenerate \
  -H "Authorization: Bearer sk_live_..."

# Response - new token includes "webhooks"
{
  "data": {
    "token": "eyJhbGciOiJSUzI1NiIs...",
    "features": ["api_access", "webhooks"]
  }
}

Use Case: Client-Side Refresh

Enable your software to refresh its license token without exposing your API key:

import requests
import jwt

class LicenseClient:
    def __init__(self, app_slug, license_id, token):
        self.app_slug = app_slug
        self.license_id = license_id
        self.token = token
        self.base_url = "https://license.yourapp.com"

    def refresh_token(self):
        """Refresh license to get latest tier features."""
        url = f"{self.base_url}/api/v1/apps/{self.app_slug}/licenses/{self.license_id}/regenerate"
        response = requests.post(url, json={"current_token": self.token})

        if response.status_code == 200:
            self.token = response.json()["data"]["token"]
            return True
        return False

    def get_features(self):
        """Decode token and return features."""
        # Note: Verify signature with public key in production
        payload = jwt.decode(self.token, options={"verify_signature": False})
        return payload.get("features", [])

Custom Features Preservation

If a license has per-license custom features (beyond the tier's features), these are preserved and merged during regeneration:

• Tier features - Updated from current tier configuration
• Custom features - Preserved from the license record
• Result - Union of both sets in the new token

Error Handling

Best Practices

• Implement automatic token refresh in your client software
• Refresh tokens periodically (e.g., daily) to get feature updates
• Cache the refreshed token locally to avoid unnecessary API calls
• Handle 400 errors gracefully - expired licenses cannot be refreshed
• Use license token auth for client-side refresh, API key for server-side bulk operations
• After key rotation, trigger regeneration for all active licenses