Managing Entitlement Expiration

This workflow covers managing entitlement expiration, including detecting expiring entitlements, handling renewals, and cleaning up expired entitlements.

Prerequisites

• API credentials with entitlement management permissions
• Entitlements with expiration dates configured
• Understanding of renewal workflows

Understanding Entitlement Expiration

When entitlements expire:

• No new leases — License server rejects new lease requests
• No lease renewals — Existing leases cannot be renewed
• Active leases — Existing leases continue until expiration (based on lease expiration, not entitlement)

Expired entitlements remain in the catalog for audit purposes but cannot issue new leases.

Step 1: Check Expiring Entitlements

Query entitlements expiring soon:

curl "${BP_BASE_URL}/v1/entitlements?expiring_within_days=30" \
  -H "Authorization: Bearer $BP_API_TOKEN"

Response:

{
  "entitlements": [
    {
      "entitlement_id": "ent_abc123",
      "tenant_id": "tenant_xyz789",
      "product_id": "prod_xyz789",
      "ends_at": "2024-12-31T23:59:59Z",
      "status": "active"
    }
  ]
}

Step 2: Check Expired Entitlements

Query expired entitlements:

curl "${BP_BASE_URL}/v1/entitlements?status=expired" \
  -H "Authorization: Bearer $BP_API_TOKEN"

Response:

{
  "entitlements": [
    {
      "entitlement_id": "ent_def456",
      "tenant_id": "tenant_xyz789",
      "product_id": "prod_xyz789",
      "ends_at": "2024-01-01T00:00:00Z",
      "status": "expired"
    }
  ]
}

Step 3: Renew Entitlement

Extend an entitlement’s expiration date:

curl -X PUT "${BP_BASE_URL}/v1/entitlements/ent_abc123" \
  -H "Authorization: Bearer $BP_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "ends_at": "2025-12-31T23:59:59Z"
  }'

Response:

{
  "entitlement_id": "ent_abc123",
  "ends_at": "2025-12-31T23:59:59Z",
  "updated_at": "2024-01-15T10:30:00Z"
}

Step 4: Configure Automated Renewal

Enable automated renewal for entitlements:

curl -X PUT "${BP_BASE_URL}/v1/entitlements/ent_abc123" \
  -H "Authorization: Bearer $BP_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "auto_renew": true,
    "renewal_days": 365
  }'

Automated renewal:

• Extends entitlement automatically before expiration
• Configurable renewal period
• Sends renewal notifications

Step 5: Send Expiration Notifications

Send notifications for expiring entitlements:

Query expiring entitlements:

curl "${BP_BASE_URL}/v1/entitlements?expiring_within_days=30" \
  -H "Authorization: Bearer $BP_API_TOKEN"

Send notifications:

• Email to tenant administrators
• Webhook to external systems
• In-app notifications
• Audit log entries

Step 6: Clean Up Expired Entitlements

Archive expired entitlements after retention period:

curl -X POST "${BP_BASE_URL}/v1/entitlements/ent_def456/archive" \
  -H "Authorization: Bearer $BP_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "Expired beyond retention period"
  }'

Retention policy:

• Keep expired entitlements for audit (e.g., 90 days)
• Archive after retention period
• Preserve audit trail

Expiration Monitoring

Monitor expiration metrics:

Key metrics:

• Number of expiring entitlements (by days until expiration)
• Number of expired entitlements
• Renewal rate (percentage renewed before expiration)
• Average time to renewal

Query metrics:

curl "${BP_BASE_URL}/v1/entitlements/metrics/expiration" \
  -H "Authorization: Bearer $BP_API_TOKEN"

Response:

{
  "expiring_7d": 5,
  "expiring_30d": 15,
  "expired": 3,
  "total_active": 100,
  "renewal_rate": 0.95
}

Expiration Alerts

Configure alerts for expiration:

Alert conditions:

• High number of entitlements expiring soon
• Entitlement expired without renewal
• Renewal failure rate above threshold

Alert configuration:

alerts:
  expiring_soon:
    threshold: 10
    days_ahead: 7
    enabled: true

  expired_without_renewal:
    threshold: 5
    enabled: true

  renewal_failure_rate:
    threshold: 0.1  # 10%
    enabled: true

Grace Periods

Some policies support grace periods for expired leases:

Policy configuration:

{
  "type": "concurrent",
  "max_seats": 25,
  "grace_period_seconds": 3600
}

Grace period behavior:

• Applies to lease expiration, not entitlement expiration
• Allows continued use after lease expiration
• Duration specified in policy

Note: Grace periods do not apply to expired entitlements. If an entitlement is expired, no new leases or renewals are allowed.

Best Practices

Proactive monitoring: Monitor expiring entitlements well in advance.

Clear notifications: Send clear expiration notifications to administrators.

Renewal workflows: Establish clear renewal workflows and processes.

Grace periods: Use grace periods appropriately (for leases, not entitlements).

Audit trail: Maintain audit trail of expiration and renewal events.

Automated cleanup: Automate cleanup of old expired entitlements.

Metrics tracking: Track expiration and renewal metrics.

Integration: Integrate with external systems for renewal management.

Next Steps

• Track license usage — see Tracking License Usage
• Revoke access — see Revoking Access
• Sync local license server — see Syncing Local License Server