Skip to content
TruthVouch Docs

Auto-Revocation and Certificate Expiry

Auto-revocation automatically revokes certificates when underlying facts change or expiry dates are reached. This guide explains revocation triggers, configuration, and user notification.

Revocation Triggers

Certificates can revoke for several reasons:

1. Fact Drift

When a truth nugget changes:

  • Value Changed: Fact updated (e.g., pricing $349 → $399)
  • Fact Deleted: Nugget removed from knowledge base
  • Major Change: Semantic shift in fact meaning
  • Addition: Conflicting fact added

2. Expiry Dates

Manual expiration after a configured duration:

  • 30 days (marketing campaigns, time-limited offers)
  • 60 days (quarterly content refresh)
  • 90 days (standard retention)
  • 1 year (evergreen content)
  • Custom dates

3. Manual Revocation

Administrator action to revoke:

client.certification.revoke_certificate(
    certificate_id="cert-123",
    reason="outdated_content",
    effective_immediately=True
)

Configuring Auto-Revocation

Per-Certificate Settings

When submitting content:

response = client.certification.submit(
    content="Your content...",
    auto_revoke_on_drift=True,
    drift_threshold=20,      # Revoke if >20% facts changed
    expiry_days=90,          # Expires in 90 days
    expiry_on_date="2024-12-31"  # Or specific date
)

Global Defaults

Set organization-wide auto-revocation policy:

client.certification.update_auto_revoke_policy(
    enabled=True,
    drift_threshold_percent=20,
    critical_categories=["pricing", "legal", "safety"],
    revoke_if_critical_changed=True,
    default_expiry_days=90
)

Drift-Based Revocation

Sensitivity Levels

Configure how sensitive revocation is to changes:

Strict:

client.certification.update_drift_sensitivity(
    level="strict",
    # Changes:
    # - Any value change → revoke
    # - Any field deletion → revoke
    # - Similarity score < 95% → revoke
)

Balanced (Default):

client.certification.update_drift_sensitivity(
    level="balanced",
    # Changes:
    # - Major value change → revoke
    # - Field deletion → revoke
    # - Similarity score < 85% → revoke
)

Lenient:

client.certification.update_drift_sensitivity(
    level="lenient",
    # Changes:
    # - Critical field change → revoke
    # - Similarity score < 70% → revoke
    # - Minor edits ignored
)

Category-Specific Rules

Different categories can have different revocation rules:

client.certification.update_revocation_rules(
    rules={
        "pricing": {
            "revoke_on_change": True,
            "sensitivity": "strict"
        },
        "company_info": {
            "revoke_on_change": True,
            "sensitivity": "balanced"
        },
        "description": {
            "revoke_on_change": False,
            "sensitivity": "lenient"
        }
    }
)

Expiry Management

Time-Based Expiry

Certificates automatically expire after specified duration:

# 90 days from now
client.certification.submit(
    content="...",
    expiry_days=90
)


# Specific date
client.certification.submit(
    content="...",
    expiry_on_date="2024-12-31"
)

Expiry Policies by Category

Different content types can have different expiry periods:

client.certification.update_expiry_policies(
    policies={
        "marketing": 30,           # 1 month
        "product_specs": 90,       # 3 months
        "compliance": 365,         # 1 year
        "evergreen": None          # No expiry
    }
)

Monitoring Revocations

Revocation Alerts

Get notified when certificates revoke:

Email Alerts:

client.certification.subscribe_to_revocation_alerts(
    email="compliance@company.com",
    alert_types=["revoked", "about_to_expire"],
    days_before_expiry=14  # Alert 2 weeks before expiry
)

Slack Integration:

client.integrations.slack.subscribe(
    event="certificate.revoked",
    channel="#content-updates",
    include_reason=True,
    include_updated_content=True
)

Revocation Dashboard

View all revoked and expiring certificates:

  1. Certification → Revocations
  2. Filter by:
    • Status (revoked, active, expiring soon)
    • Reason (drift, expiry, manual)
    • Date range
  3. Export report

API Access

# Get all revoked certificates
revoked = client.certification.get_revoked_certificates(
    since="2024-01-01",
    reason="drift"
)


for cert in revoked:
    print(f"Certificate {cert.id}:")
    print(f"  Reason: {cert.revocation_reason}")
    print(f"  Date: {cert.revoked_at}")
    print(f"  Details: {cert.drift_details}")


# Get expiring soon
expiring = client.certification.get_expiring_certificates(
    within_days=30
)

Handling Revocations

User-Facing Notifications

Configure how users are notified:

Badge Behavior:

# Option 1: Badge disappears
TruthVouch.Badge.render('cert-123', elem, {
  hideWhenRevoked: true
});


// Option 2: Badge shows revoked state
TruthVouch.Badge.render('cert-123', elem, {
  hideWhenRevoked: false,
  revokedTemplate: '<p>This content is no longer verified</p>'
});

Webhook Notification:

client.webhooks.subscribe(
    event="certification.revoked",
    url="https://example.com/hooks/cert-revoked"
)

Content Updates

When a certificate is revoked, update your content:

Option 1: Update Content

# Retrieve reason for revocation
cert = client.certification.get("cert-123")
if cert.revoked:
    print(f"Revoked because: {cert.revocation_reason}")


    # Update content with new information
    new_cert = client.certification.submit(
        content="Updated content with current facts...",
        replaces_certificate="cert-123",
        version="2.0"
    )

Option 2: Archive Content

# Mark content as archived, remove from public
client.certification.archive_content(
    certificate_id="cert-123",
    reason="facts_changed",
    redirect_to="https://example.com/updated-guide"
)

Option 3: Re-Certify

# Re-verify existing content to see current score
cert = client.certification.reverify("cert-123")
if cert.trust_score >= 75:
    # Still valid, just update date
    client.certification.extend_expiry("cert-123", days=90)

Revocation Workflows

Marketing Campaign

Campaigns with time-limited offers:

batch = client.certification.batch_submit(
    documents=campaign_docs,
    batch_name="flash-sale-jan-2024",
    auto_revoke_on_drift=False,  # Don't revoke on price changes
    expiry_on_date="2024-02-01"  # Hard stop after campaign ends
)

Compliance Document

Compliance docs with regulatory review period:

response = client.certification.submit(
    content="GDPR Compliance Report Q4 2023",
    auto_revoke_on_drift=True,   # Revoke if regs change
    drift_threshold=10,            # Very strict
    expiry_days=365,               # Annual review
    tags=["compliance", "gdpr"]
)

Product Documentation

Evergreen docs that update when product changes:

response = client.certification.submit(
    content="API Documentation",
    auto_revoke_on_drift=True,
    drift_threshold=30,            # Balanced
    expiry_days=None,              # No expiry
    # Manual revoke only when needed
)

Certificate Lifecycle

ACTIVE (just issued)
  ↓
MONITORING (hourly drift checks)
  ↓
[ REVOKED (drift detected) ] OR [ EXPIRING SOON (14 days before expiry) ]
  ↓
REVOKED (auto-revoke triggered or expiry date reached)
  ↓
ARCHIVED (after 90 days, moved to archive for records)

Best Practices

1. Match Expiry to Content Type

  • Marketing: 30-60 days (refresh frequently)
  • Product Docs: 90 days (annual updates)
  • Compliance: 1 year (regulatory cycles)
  • Evergreen: No expiry (permanent content)

2. Use Drift-Based Revocation for Critical Info

# Pricing must be current
client.certification.submit(
    content="Pricing sheet",
    auto_revoke_on_drift=True,
    drift_threshold=5,  # Very strict
    categories_to_monitor=["pricing"]
)

3. Monitor and Respond

Set up alerts and plan your response:

# Weekly revocation report
report = client.certification.get_revocation_report(
    period="last_7_days"
)
print(f"Revoked this week: {report.revoked_count}")
print(f"Expiring soon: {report.expiring_count}")

4. Document Revocation Reasons

Always capture why a certificate was revoked:

client.certification.revoke_certificate(
    certificate_id="cert-123",
    reason="pricing_change",
    details="Starter plan price changed from $349 to $399",
    suggested_action="re_certify"
)

Next Steps

  • Monitoring: Set up drift alerts
  • Badge Updates: Configure badge behavior on revocation
  • Integration: Connect revocation webhooks to your systems