License Enforcement

Audience: Control Core administrators Time: ~10 min read

This guide explains how license enforcement works in Control Core, which API paths are gated, and how to apply an Extension Code when a trial expires.

Overview

Control Core uses license enforcement to ensure:

• Subscription verification: Valid subscription status is verified
• Feature gating: Trial-expired customers cannot create or activate policies
• Trial management: Trial periods are tracked and enforced
• Usage compliance: Bouncer-pair limits are enforced

How license enforcement works

License Server connection

Control Core requires a connection to the License Server for:

• Policy testing (Control Simulator)
• Production promotion (sandbox → production)
• Subscription sync (keeping tier / days remaining current)

Trial-expired posture

When a customer's trial has expired and no valid license token is present, the Control Plane returns HTTP 403 with a structured body on every policy create/activate path. The body has a stable code field so the UI can offer the right next step:

{
  "code": "license_required_for_create" ,
  "reason": "trial_expired",
  "message": "Trial period has expired.",
  "trial_end_date": "2026-04-01T00:00:00",
  "extension_code_supported": true
}

The matching code for activation is license_required_for_activate.

Routes that are gated

Without License Server connection (trial expired)

You CANNOT:

• Create new policies (UI, OEM SDK, Policies-as-Code, IDE plugins)
• Enable, promote, or deploy policies
• Test policies (Control Simulator)

You CAN:

• View existing policies and policy templates
• Read audit logs and dashboards
• Apply an Extension Code in Settings → General → Telemetry

Without License Server connection (trial active)

During an active trial all paths above remain open even without a license token.

With License Server connection

If License Server is connected:

All Features Available:

• Policy testing enabled
• Production promotion enabled
• Full feature access
• Subscription status synced

Feature Gating

Policy Testing

Requirement: License Server connection required

What It Does:

• Allows you to test policies before deployment
• Simulates policy impact on access decisions
• Validates policy logic and performance

If Not Licensed:

• Policy testing button is disabled
• Error message: "Connect to Control Core License Server in General Settings (Telemetry tab) to enable policy testing"

To Enable:

1. Navigate to Settings → General → Telemetry
2. Configure License Admin URL and API Key
3. Test connection
4. Save configuration

Production Promotion

Requirement: License Server connection required

What It Does:

• Promotes policies from Sandbox to Production
• Enables production deployment
• Activates production bouncers

If Not Licensed:

• Promote button is disabled
• Error message: "Connect to Control Core License Server in General Settings (Telemetry tab) to enable production deployment"

To Enable:

1. Configure License Server connection (see above)
2. Verify subscription tier is active
3. Check trial expiration (if on Kickstart plan)

Trial Expiration

For Kickstart Plan:

• During Trial: All features available
• After Trial Expires: Production promotion disabled
• Warning: 7 days before expiration, warnings appear

Trial Status Indicators:

• Active: Trial is active, features available
• Expiring Soon: 7 days or less remaining
• Expired: Trial expired, upgrade required

Checking License Status

View License Status

1. Navigate to Settings → General → Telemetry
2. Review License Connection Required alert (if not connected)
3. Check connection status in telemetry configuration

License Status Endpoint

The system provides a license status API endpoint:

• Endpoint: GET /telemetry/license-status
• Returns: Connection status, tier, trial info, feature gates

Status Fields:

• connected: Boolean - License Server connection status
• tier: String - Subscription tier (kickstart, custom)
• trial_expired: Boolean - Trial expiration status
• trial_days_remaining: Integer - Days until trial expires
• can_test_policies: Boolean - Policy testing allowed
• can_promote_to_production: Boolean - Production promotion allowed
• warning: String - Warning messages (if any)

Troubleshooting License Issues

Cannot Test Policies

Issue: Policy testing is disabled

Diagnosis:

1. Check License Server connection status
2. Verify telemetry configuration
3. Test connection using "Test Connection" button

Solutions:

1. Configure License Admin URL in Settings → General → Telemetry
2. Enter valid API Key
3. Test connection
4. Save configuration
5. Refresh page and try again

Cannot Promote to Production

Issue: Production promotion is disabled

Possible Causes:

1. License Server not connected
2. Trial expired (Kickstart plan)
3. Subscription status inactive

Solutions:

If License Server Not Connected:

1. Configure License Server connection (see above)
2. Test connection
3. Save configuration

If Trial Expired:

1. Check trial expiration date on Subscription page
2. Contact support to extend trial or upgrade
3. Verify subscription tier is active

If Subscription Inactive:

1. Check subscription status
2. Contact support to reactivate subscription
3. Verify License Server connection is active

License Server Connection Fails

Issue: "Test Connection" fails

Diagnosis:

1. Check License Admin URL is correct
2. Verify API Key is valid
3. Check network connectivity
4. Review error message details

Solutions:

1. Verify URL:

   • Check for typos in License Admin URL
   • Ensure URL includes https:// protocol
   • Verify URL is accessible from your network

2. Verify API Key:

   • Check API key is correct (no extra spaces)
   • Verify API key hasn't expired
   • Contact support to regenerate API key if needed

3. Check Network:

   • Verify firewall allows outbound HTTPS to License Server
   • Check proxy settings if behind corporate proxy
   • Test URL accessibility from server: curl https://business-admin.controlcore.io/health

4. Review Logs:

   • Check backend logs for detailed error messages
   • Look for connection timeout or SSL errors
   • Verify DNS resolution is working

Trial Expired Message

Issue: "Trial period has expired" message

Solutions:

1. Apply an Extension Code if Control Core support has issued one (see "Apply Extension Code" below).

2. Check trial expiration date on Subscription page

3. Contact support to:

   • Extend trial period
   • Upgrade to Custom plan
   • Verify subscription status

4. Ensure License Server connection is active (for subscription sync)

Subscription Tier Not Updating

Issue: Subscription tier doesn't match License Server

Solutions:

1. Verify License Server connection is active
2. Check telemetry transmission is working
3. License Server webhook should update tier automatically
4. Contact support if tier doesn't sync after 24 hours

Best Practices

Maintaining License Connection

1. Monitor Connection Status:

   • Regularly check telemetry health status
   • Review transmission history for failures
   • Test connection periodically

2. Keep Configuration Updated:

   • Update API keys before expiration
   • Verify License Admin URL is current
   • Test connection after configuration changes

3. Troubleshoot Promptly:

   • Address connection issues immediately
   • Review error messages in transmission history
   • Contact support if issues persist

Trial Management

1. Track Trial Expiration:

   • Monitor trial days remaining
   • Plan upgrade before expiration
   • Request extension if needed

2. Understand Trial Limits:

   • Trial includes all features
   • Production deployment available during trial
   • Upgrade required after expiration

Apply Extension Code

When a Control Core operator (support / customer success) issues you a License Extension Code by email, you redeem it on your Control Plane:

1. Sign in to the Control Plane as an admin
2. Open Settings → General → Telemetry
3. Click Apply Extension Code
4. Paste the code your support contact sent (it's a long <base64>.<base64> string with no whitespace)
5. Click Apply

If the code is valid, the Control Plane:

• ES256-verifies the signature against the embedded public key
• Confirms the code has not been redeemed before (replay protected)
• Confirms the code has not expired and was issued for your customer record
• Extends your trial / paid window by the encoded number of days
• Records the redemption in license_extension_redemptions for audit
• Sends the code_id back to the License Server on the next telemetry tick so the operator's UI shows the code as redeemed

Single use: A code that has been redeemed cannot be redeemed again (HTTP 409). If you need another extension, your support contact must issue a fresh code.

Common errors

Related Guides

• Subscription Management - Understand subscription plans
• Telemetry Management - Configure License Server connection
• General Settings - Platform configuration