Revoking Access

This workflow covers revoking access to software by revoking entitlements and terminating active license leases. Use this when licenses expire, are cancelled, or need to be revoked for compliance reasons.

Prerequisites

• API credentials with entitlement management permissions
• Entitlement ID or subject information
• Understanding of which licenses need to be revoked

Understanding Access Revocation

Access revocation involves:

1. Revoking entitlements — Prevents new leases from being issued
2. Terminating active leases — Immediately invalidates active license tokens
3. Cleaning up resources — Ensures all access is properly terminated

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

Step 1: Identify Entitlements to Revoke

Find entitlements to revoke:

By tenant:

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

By product:

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

By subject:

curl "${BP_BASE_URL}/v1/license/status?product_id=prod_xyz789&subject_type=user&subject_id=user_123" \
  -H "Authorization: Bearer $BP_API_TOKEN"

Step 2: Check Active Leases

Check for active leases before revoking:

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

Response:

{
  "entitlement_id": "ent_abc123",
  "active_leases": [
    {
      "lease_id": "lease_xyz789",
      "subject_type": "user",
      "subject_id": "user_123",
      "issued_at": "2024-01-15T09:00:00Z",
      "expires_at": "2024-01-15T11:00:00Z"
    }
  ]
}

Step 3: Revoke Entitlement

Revoke the entitlement:

curl -X POST "${BP_BASE_URL}/v1/entitlements/ent_abc123/revoke" \
  -H "Authorization: Bearer $BP_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "License expired",
    "revoke_active_leases": true
  }'

Parameters:

• reason — Reason for revocation (required for audit)
• revoke_active_leases — Whether to immediately terminate active leases (default: true)

Response:

{
  "entitlement_id": "ent_abc123",
  "status": "revoked",
  "revoked_at": "2024-01-15T10:30:00Z",
  "revoked_by": "admin@example.com",
  "reason": "License expired",
  "leases_revoked": 5
}

Step 4: Terminate Specific Leases (Optional)

If you need to terminate specific leases without revoking the entitlement:

curl -X POST "${BP_BASE_URL}/v1/license/lease/revoke" \
  -H "Authorization: Bearer $BP_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "lease_id": "lease_xyz789",
    "reason": "User account terminated"
  }'

Response:

{
  "lease_id": "lease_xyz789",
  "status": "revoked",
  "revoked_at": "2024-01-15T10:30:00Z",
  "revoked_by": "admin@example.com"
}

Step 5: Verify Revocation

Verify access has been revoked:

Check entitlement status:

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

Check lease status:

curl "${BP_BASE_URL}/v1/license/status?product_id=prod_xyz789&subject_type=user&subject_id=user_123" \
  -H "Authorization: Bearer $BP_API_TOKEN"

Revoked entitlements return status: "revoked" and cannot issue new leases.

Bulk Revocation

Revoke multiple entitlements:

# List entitlements to revoke
ENTITLEMENTS=$(curl "${BP_BASE_URL}/v1/tenants/tenant_abc123/entitlements" \
  -H "Authorization: Bearer $BP_API_TOKEN" | jq -r '.[] | select(.ends_at < "2024-01-15") | .entitlement_id')

# Revoke each entitlement
for ENT_ID in $ENTITLEMENTS; do
  curl -X POST "${BP_BASE_URL}/v1/entitlements/$ENT_ID/revoke" \
    -H "Authorization: Bearer $BP_API_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "reason": "Bulk revocation: licenses expired",
      "revoke_active_leases": true
    }'
done

Revocation Scenarios

Scenario 1: License Expiration

When an entitlement expires:

1. Entitlement automatically stops issuing new leases
2. Active leases continue until expiration
3. Optionally revoke entitlement and terminate active leases immediately

Scenario 2: License Cancellation

When a license is cancelled:

1. Revoke entitlement immediately
2. Terminate all active leases
3. Document cancellation reason

Scenario 3: Compliance Violation

When access must be revoked for compliance:

1. Revoke entitlement immediately
2. Terminate all active leases
3. Document compliance reason
4. Notify relevant stakeholders

Monitoring Revocation Impact

Monitor the impact of revocations:

Check revoked entitlements:

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

Monitor lease terminations:

• Track number of leases revoked
• Monitor client reconnection attempts
• Alert on unexpected revocation patterns

Best Practices

Document reasons: Always include a reason when revoking access for audit purposes.

Revoke active leases: Terminate active leases when revoking entitlements to ensure immediate effect.

Verify revocation: Confirm access has been revoked after revocation.

Monitor impact: Track revocation metrics and client behavior.

Maintain audit trail: Revoked entitlements remain in the catalog for audit purposes.

Notify stakeholders: Notify affected users and administrators about access revocation.

Next Steps

• Track license usage — see Tracking License Usage
• Manage entitlement expiration — see Managing Entitlement Expiration
• Configure automatic expiration — see Managing Update Policies