SSL Certificate Lifecycle

This guide explains how SSL certificate provisioning works in VanityCert, from domain creation through certificate issuance and renewal.

Overview

When you add a domain to VanityCert, an automated process validates your domain ownership, requests an SSL certificate, and monitors the certificate until it's successfully installed. The entire process typically takes 15-45 minutes.

Lifecycle Stages

Domain Created
    ↓
DNS Validation (5-30 min)
    ↓
Certificate Request (1-5 min)
    ↓
Certificate Issuance (1-5 min)
    ↓
Active Certificate
    ↓
Auto-Renewal (every 90 days)

Stage 1: Domain Creation

When you add a domain via API or dashboard:

curl -X POST https://app.vanitycert.com/api/domains \
  -H "X-API-KEY-ID: vc_pk_abc123def456" \
  -H "X-API-KEY: sk_1234567890abcdef1234567890abcdef" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "app.yourdomain.com",
    "server_id": 123
  }'

Initial Status:

{
  "dns_status": "pending",
  "ssl_status": "pending"
}

What happens next:

Domain is saved to your organization
DNS validation process begins automatically
You'll receive a domain.created webhook event (if configured)

Action Required:

Configure DNS CNAME record pointing to my.vanitycert.com
See DNS Configuration Guide

Stage 2: DNS Validation

VanityCert validates that you own the domain by checking for a CNAME record.

Expected DNS Configuration:

app.yourdomain.com.  IN  CNAME  my.vanitycert.com.

Validation Process:

Initial Check - Immediately after domain creation
- Queries DNS for CNAME record
- Checks if target is my.vanitycert.com
Retry Loop - If validation fails
- Retries every 5 minutes
- Continues for up to 24 hours
Success - CNAME found
- Updates status to dns_status: "validated"
- Proceeds to certificate request
- Sends certificate.validation_succeeded webhook
Timeout - After 24 hours
- Marks status as dns_status: "error"
- Sends certificate.validation_failed webhook
- Sends email notification (if configured)

Timeline:

Best case: 1-5 minutes (if DNS already configured)
Typical: 5-30 minutes (DNS propagation time)
Maximum: 24 hours before timeout

Check Status:

curl -X GET https://app.vanitycert.com/api/domains/456 \
  -H "X-API-KEY-ID: vc_pk_abc123def456" \
  -H "X-API-KEY: sk_1234567890abcdef1234567890abcdef"

Response:

{
  "dns_status": "validated",
  "dns_validated_at": "2025-01-01T12:05:00Z"
}

Common Issues:

CNAME not configured → Configure DNS
CNAME points to wrong target → Update to my.vanitycert.com
DNS not propagated → Wait 5-30 minutes
Cloudflare proxy enabled → Disable (use DNS only)

Stage 3: Certificate Request

Once DNS is validated, VanityCert requests an SSL certificate from the certificate authority.

What happens:

Certificate Request Submitted
- VanityCert sends certificate request to ACME provider
- Includes domain name and validation proof
- HTTP-01 challenge performed automatically
Request Tracking
- Certificate request ID is stored
- Status monitoring begins
Success
- Request accepted by certificate authority
- Certificate issuance begins
- You'll receive confirmation
Failure (rare)
- Status updated to ssl_status: "error"
- Error details available in dashboard
- Automatic retries attempted

Timeline: 1-5 minutes

Status:

{
  "ssl_status": "pending",
  "certificate_request_id": "abc123def456"
}

Stage 4: Certificate Issuance

The certificate authority processes your request and issues the SSL certificate.

What happens:

Certificate Generation
- Certificate authority validates your domain
- Generates SSL certificate
- Signs certificate with their root CA
Status Monitoring
- VanityCert polls for certificate status
- Checks every 5 minutes
- Waits for issued status
Certificate Installation
- Certificate is retrieved
- Installed on your designated server
- Domain status updated
Completion
- Status: ssl_status: "active"
- Renewal date set (90 days)
- certificate.issued webhook sent

Timeline: 1-5 minutes (rarely longer)

Final Status:

{
  "dns_status": "validated",
  "ssl_status": "active",
  "last_renewed": "2025-01-01T12:10:00Z",
  "renews_on": "2025-04-01"
}

Certificate Details:

Validity Period: 90 days
Certificate Type: Domain Validation (DV)
Encryption: RSA 2048-bit or higher
Protocol Support: TLS 1.2, TLS 1.3

Stage 5: Active Certificate

Your certificate is now active and serving traffic.

What this means:

SSL/TLS encryption is enabled
Certificate is installed on your server
Traffic is being secured
Certificate will auto-renew before expiration

Monitor Your Certificate:

Via API:

curl -X GET https://app.vanitycert.com/api/domains/456 \
  -H "X-API-KEY-ID: vc_pk_abc123def456" \
  -H "X-API-KEY: sk_1234567890abcdef1234567890abcdef"

Via Dashboard:

View all certificates: /dashboard/domains
Certificate details: /dashboard/domains/456
Expiry report: /dashboard/reports/certificate-expiry

Certificate Information:

{
  "ssl_status": "active",
  "last_renewed": "2025-01-01T12:10:00Z",
  "renews_on": "2025-04-01",
  "days_until_renewal": 90
}

Stage 6: Automatic Renewal

Certificates automatically renew before they expire.

Renewal Process:

Pre-Renewal Check (14 days before expiry)
- DNS validation re-checked
- Server health verified
- If DNS invalid, certificate may be removed
Renewal Trigger (30 days before expiry)
- Automatic renewal initiated
- New certificate requested
- Old certificate replaced seamlessly
Renewal Success
- New certificate installed
- Renewal date extended (+90 days)
- certificate.renewal_succeeded webhook sent
Renewal Failure (if issues occur)
- Status: ssl_status: "error"
- Email notification sent
- certificate.renewal_failed webhook sent
- Manual intervention may be required

Timeline:

Renewal starts: 30 days before expiry
Pre-check: 14 days before expiry

What you need to do:

✅ Nothing! Renewals are automatic
✅ Keep DNS CNAME record in place
✅ Monitor webhook events for failures

Renewal Notifications:

Via webhook:

{
  "event": "certificate.renewal_succeeded",
  "domain_url": "app.yourdomain.com",
  "renewed_at": "2025-03-02T12:00:00Z",
  "renews_on": "2025-06-01"
}

Via email (if notifications enabled):

Renewal success confirmation
Renewal failure alerts
Expiry warnings (if renewal fails)

Certificate Expiry

If a certificate is not renewed and expires:

What happens:

Expiry Warning (7 days before)
- Email notification sent
- Webhook event triggered
- Dashboard shows warning
Certificate Expires
- Status: ssl_status: "expired"
- Traffic may be affected
- Browser warnings for users
Resolution
- Automatic renewal attempted
- If DNS still valid, new cert issued
- If DNS invalid, manual fix required

Prevent Expiry:

Keep DNS CNAME records in place
Monitor renewal notifications
Set up webhook alerts
Check dashboard regularly

Status Reference

DNS Status

Status	Meaning	Action Required
`pending`	Waiting for DNS validation	Configure CNAME record
`validated`	DNS successfully validated	None - automatic
`error`	DNS validation failed after 24h	Fix CNAME, recreate domain

SSL Status

Status	Meaning	Action Required
`pending`	Waiting for certificate	None - automatic
`active`	Certificate issued and active	None
`error`	Certificate issuance failed	Check error details, retry
`expired`	Certificate has expired	Check DNS, contact support

Monitoring Certificate Status

Via API

Get domain details:

curl -X GET https://app.vanitycert.com/api/domains/456 \
  -H "X-API-KEY-ID: vc_pk_abc123def456" \
  -H "X-API-KEY: sk_1234567890abcdef1234567890abcdef"

List expiring certificates:

curl -X GET "https://app.vanitycert.com/api/domains?expires_within=30" \
  -H "X-API-KEY-ID: vc_pk_abc123def456" \
  -H "X-API-KEY: sk_1234567890abcdef1234567890abcdef"

Filter by status:

curl -X GET "https://app.vanitycert.com/api/domains?ssl_status=active" \
  -H "X-API-KEY-ID: vc_pk_abc123def456" \
  -H "X-API-KEY: sk_1234567890abcdef1234567890abcdef"

Via Dashboard

All Domains: /dashboard/domains

Certificate Expiry Report: /dashboard/reports/certificate-expiry

Shows all certificates sorted by expiration date.

Certificate Audit Log: /dashboard/reports/certificate-audit

Complete history of all certificate events.

Via Webhooks

Set up webhooks to receive real-time notifications:

app.post('/webhooks/vanitycert', (req, res) => {
  const event = req.body;

  if (event.event === 'certificate.issued') {
    console.log(`Certificate issued for ${event.domain_url}`);
    // Update your database, send notification, etc.
  }

  if (event.event === 'certificate.renewal_failed') {
    console.error(`Renewal failed for ${event.domain_url}: ${event.reason}`);
    // Alert ops team, create ticket, etc.
  }

  res.status(200).send('OK');
});

Troubleshooting

Domain Stuck in "Pending" Status

Symptoms:

dns_status: "pending" for >30 minutes
No progress in certificate issuance

Diagnosis:

Check DNS configuration:

dig app.yourdomain.com CNAME

Expected output:

app.yourdomain.com. 300 IN CNAME my.vanitycert.com.

Verify CNAME target is exactly my.vanitycert.com
Check for conflicting A/AAAA records

Resolution:

Add/fix CNAME record
Wait 5-30 minutes for DNS propagation
Check status again

DNS Validation Failed

Symptoms:

dns_status: "error" after 24 hours
Email notification received

Common Causes:

CNAME not configured
CNAME pointing to wrong target
Cloudflare proxy enabled
DNS propagation delayed

Resolution:

Fix DNS configuration
Delete and recreate domain
Validation will retry automatically

Certificate Issuance Failed

Symptoms:

ssl_status: "error"
DNS validated but certificate not issued

Diagnosis:

Check error message in dashboard
Review certificate audit log

Resolution:

Contact support with domain ID
Provide error details from dashboard
May require manual intervention

Certificate Not Renewing

Symptoms:

Certificate expiring soon
No renewal activity

Common Causes:

DNS CNAME removed
Server configuration changed
Network connectivity issues

Resolution:

Verify DNS CNAME still exists
Check domain status in dashboard
Contact support if DNS is valid

Best Practices

Before Creating Domains

✅ Configure DNS first

Add CNAME records before creating domains in VanityCert for faster validation.

✅ Use consistent naming

Follow a naming convention for subdomains (e.g., app, api, www).

✅ Document your setup

Keep track of which domains are managed by VanityCert.

Monitoring

✅ Set up webhooks

Receive real-time notifications for all certificate events.

✅ Check expiry report weekly

Review the certificate expiry report to catch any issues early.

✅ Monitor renewal notifications

Pay attention to renewal success/failure notifications.

DNS Management

✅ Keep CNAME records permanent

Don't remove CNAME records - they're needed for renewals.

✅ Use low TTL during setup

Set TTL to 300 seconds (5 minutes) during initial setup.

✅ Document DNS changes

Track all DNS changes in your change log.

Security

✅ Verify certificate installation

Test your domains to ensure SSL is working:

curl -vI https://app.yourdomain.com

✅ Monitor for expiry

Set up alerts for certificates expiring in < 14 days.

✅ Test renewal process

Verify renewal webhooks are working before certificates expire.

Performance Optimization

Faster Provisioning

Configure DNS before adding domains:

Add CNAME records first
Wait 5 minutes for propagation
Then create domains in VanityCert
Validation will succeed on first check

Bulk domain creation:

Use the bulk API to add multiple domains efficiently:

curl -X POST https://app.vanitycert.com/api/domains/bulk \
  -H "X-API-KEY-ID: vc_pk_abc123def456" \
  -H "X-API-KEY: sk_1234567890abcdef1234567890abcdef" \
  -H "Content-Type: application/json" \
  -d '{
    "domains": [
      {"url": "app1.yourdomain.com", "server_id": 123},
      {"url": "app2.yourdomain.com", "server_id": 123}
    ]
  }'

Next Steps

DNS Configuration - Detailed DNS setup guide
Webhooks - Set up real-time notifications
Error Handling - Troubleshooting guide
API Reference - Complete API documentation

Support

Need help with SSL certificates?

Email: support@vanitycert.com Dashboard: https://app.vanitycert.com/support Status: https://status.vanitycert.com Documentation: https://docs.vanitycert.com

Overview​

Lifecycle Stages​

Stage 1: Domain Creation​

Stage 2: DNS Validation​

Stage 3: Certificate Request​

Stage 4: Certificate Issuance​

Stage 5: Active Certificate​

Stage 6: Automatic Renewal​

Certificate Expiry​

Status Reference​

DNS Status​

SSL Status​

Monitoring Certificate Status​

Via API​

Via Dashboard​

Via Webhooks​

Troubleshooting​

Domain Stuck in "Pending" Status​

DNS Validation Failed​

Certificate Issuance Failed​

Certificate Not Renewing​

Best Practices​

Before Creating Domains​

Monitoring​

DNS Management​

Security​

Performance Optimization​

Faster Provisioning​

Next Steps​

Support​

Overview

Lifecycle Stages

Stage 1: Domain Creation

Stage 2: DNS Validation

Stage 3: Certificate Request

Stage 4: Certificate Issuance

Stage 5: Active Certificate

Stage 6: Automatic Renewal

Certificate Expiry

Status Reference

DNS Status

SSL Status

Monitoring Certificate Status

Via API

Via Dashboard

Via Webhooks

Troubleshooting

Domain Stuck in "Pending" Status

DNS Validation Failed

Certificate Issuance Failed

Certificate Not Renewing

Best Practices

Before Creating Domains

Monitoring

DNS Management

Security

Performance Optimization

Faster Provisioning

Next Steps

Support