DNS Configuration

To provision SSL certificates with VanityCert, you need to configure DNS records for your domains. This guide explains how to set up DNS correctly.

Overview

VanityCert uses CNAME records to validate domain ownership and route traffic for SSL certificate provisioning.

Required DNS Record:

{your-domain}  IN  CNAME  my.vanitycert.com

This tells DNS resolvers to point your domain to VanityCert's infrastructure for certificate validation and management.

Why CNAME Records?

CNAME (Canonical Name) records allow VanityCert to:

Validate Ownership - Proves you control the domain
Handle Certificate Challenges - Respond to ACME HTTP-01 challenges
Serve Certificates - Deliver SSL certificates to your backend servers
Manage Renewals - Automatically renew certificates without DNS changes

Quick Setup

Step 1: Find Your Domain

After adding a domain via API or dashboard, note the domain URL you want to secure:

app.yourdomain.com

Step 2: Add CNAME Record

In your DNS provider, add a CNAME record:

Field	Value
Type	CNAME
Name	`app` (or full subdomain)
Target	`my.vanitycert.com`
TTL	300 (5 minutes) or your provider's default

Step 3: Verify DNS

Use dig or nslookup to verify:

dig app.yourdomain.com CNAME

# Expected output:
# app.yourdomain.com. 300 IN CNAME my.vanitycert.com.

nslookup -type=CNAME app.yourdomain.com

# Expected output:
# app.yourdomain.com canonical name = my.vanitycert.com

Provider-Specific Instructions

Cloudflare

Log in to Cloudflare dashboard
Select your domain
Go to DNS → Records
Click Add record
Configure:
- Type: CNAME
- Name: app (your subdomain)
- Target: my.vanitycert.com
- Proxy status: DNS only (grey cloud) ⚠️
- TTL: Auto
Click Save

Important: Disable Cloudflare proxy (use DNS only). The orange cloud must be grey for VanityCert to work.

AWS Route 53

Via Console:

Open Route 53 console
Select your hosted zone
Click Create record
Configure:
- Record name: app (your subdomain)
- Record type: CNAME
- Value: my.vanitycert.com
- TTL: 300 seconds
- Routing policy: Simple routing
Click Create records

Via AWS CLI:

aws route53 change-resource-record-sets \
  --hosted-zone-id Z1234567890ABC \
  --change-batch '{
    "Changes": [{
      "Action": "CREATE",
      "ResourceRecordSet": {
        "Name": "app.yourdomain.com",
        "Type": "CNAME",
        "TTL": 300,
        "ResourceRecords": [{"Value": "my.vanitycert.com"}]
      }
    }]
  }'

Via Terraform:

resource "aws_route53_record" "vanitycert" {
  zone_id = aws_route53_zone.main.zone_id
  name    = "app.yourdomain.com"
  type    = "CNAME"
  ttl     = 300
  records = ["my.vanitycert.com"]
}

Google Cloud DNS

Via Console:

Go to Cloud DNS
Select your DNS zone
Click Add record set
Configure:
- DNS name: app.yourdomain.com
- Resource record type: CNAME
- TTL: 5 minutes
- Canonical name: my.vanitycert.com
Click Create

Via gcloud CLI:

gcloud dns record-sets create app.yourdomain.com \
  --zone=your-zone-name \
  --type=CNAME \
  --ttl=300 \
  --rrdatas=my.vanitycert.com

GoDaddy

Log in to GoDaddy account
Go to My Products → DNS
Click Add under Records
Configure:
- Type: CNAME
- Host: app (your subdomain)
- Points to: my.vanitycert.com
- TTL: 1 Hour (or custom)
Click Save

Namecheap

Log in to Namecheap
Go to Domain List → Select domain
Click Advanced DNS
Click Add New Record
Configure:
- Type: CNAME Record
- Host: app (your subdomain)
- Value: my.vanitycert.com
- TTL: Automatic
Click green checkmark to save

Vercel DNS

Go to your domain settings in Vercel
Click Add under DNS Records
Configure:
- Type: CNAME
- Name: app
- Value: my.vanitycert.com
- TTL: 60 (default)
Click Add

DNS Propagation

After adding the CNAME record, DNS changes need to propagate.

Typical Propagation Times:

Immediate to 5 minutes: Most modern DNS providers
5 to 30 minutes: Common for most configurations
Up to 24 hours: Maximum (very rare)

Check Propagation:

# Check from multiple locations
dig @8.8.8.8 app.yourdomain.com CNAME     # Google DNS
dig @1.1.1.1 app.yourdomain.com CNAME     # Cloudflare DNS
dig @208.67.222.222 app.yourdomain.com CNAME  # OpenDNS

Online Tools:

Validation Timeline

Once DNS is configured, VanityCert validates your domain:

Initial Check - Immediately after domain creation
Retry Interval - Every 5 minutes if validation fails
Timeout - After 24 hours, domain marked as failed
Success - Certificate issuance begins

Track Validation:

# Check domain 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",  // pending → validated → error
  "dns_validated_at": "2025-01-01T12:05:00Z"
}

Multiple Domains

To add multiple subdomains, create separate CNAME records for each:

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

Bulk DNS Configuration (Route 53 example):

aws route53 change-resource-record-sets \
  --hosted-zone-id Z1234567890ABC \
  --change-batch '{
    "Changes": [
      {
        "Action": "CREATE",
        "ResourceRecordSet": {
          "Name": "app.yourdomain.com",
          "Type": "CNAME",
          "TTL": 300,
          "ResourceRecords": [{"Value": "my.vanitycert.com"}]
        }
      },
      {
        "Action": "CREATE",
        "ResourceRecordSet": {
          "Name": "api.yourdomain.com",
          "Type": "CNAME",
          "TTL": 300,
          "ResourceRecords": [{"Value": "my.vanitycert.com"}]
        }
      }
    ]
  }'

Wildcard Domains

VanityCert does not currently support wildcard certificates (*.yourdomain.com).

Instead, add each subdomain individually:

app.yourdomain.com
api.yourdomain.com
dashboard.yourdomain.com

Apex Domains

CNAME records cannot be added to apex domains (e.g., yourdomain.com) due to DNS specifications.

Workarounds:

Option 1: Use Subdomain (Recommended)

app.yourdomain.com  →  CNAME my.vanitycert.com

Redirect apex to subdomain:

yourdomain.com  →  301 redirect to  https://app.yourdomain.com

Option 2: ALIAS Record (DNS Provider Support Required)

Some DNS providers support ALIAS or ANAME records that work like CNAME for apex domains:

Route 53 ALIAS:

resource "aws_route53_record" "apex" {
  zone_id = aws_route53_zone.main.zone_id
  name    = "yourdomain.com"
  type    = "A"

  alias {
    name                   = "my.vanitycert.com"
    zone_id               = "Z<VANITYCERT_ZONE_ID>"
    evaluate_target_health = false
  }
}

Cloudflare Flattening:

Cloudflare automatically flattens CNAME records at the apex. You can add:

yourdomain.com  CNAME  my.vanitycert.com  (DNS only, not proxied)

Troubleshooting

DNS Not Validated After 30 Minutes

Check 1: Verify CNAME exists

dig app.yourdomain.com CNAME

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

If no CNAME found:

Verify record was saved in DNS provider
Check for typos in subdomain or target
Ensure TTL has expired (wait for propagation)

Check 2: Verify CNAME target

CNAME must point to exactly my.vanitycert.com (with or without trailing dot):

✅ my.vanitycert.com
✅ my.vanitycert.com.
❌ www.vanitycert.com
❌ vanitycert.com

Check 3: Check for conflicting records

Remove any A or AAAA records for the same subdomain:

dig app.yourdomain.com A
dig app.yourdomain.com AAAA

These should return no results. If they do, delete those records.

Check 4: Cloudflare proxy mode

If using Cloudflare, ensure proxy is disabled (grey cloud):

Orange cloud = proxied (won't work ❌)
Grey cloud = DNS only (will work ✅)

Domain Stuck in "Pending" Status

Possible Causes:

DNS not configured correctly
DNS not yet propagated
CNAME pointing to wrong target

Resolution:

Verify DNS configuration (see checks above)
Wait for DNS propagation (up to 24 hours)
Check domain status in dashboard or via API
Contact support if stuck after 24 hours

"CNAME Record Not Found" Error

This means:

DNS query returned no CNAME record
CNAME exists but points to wrong target
DNS not yet propagated

Fix:

Verify CNAME exists in your DNS provider
Verify target is exactly my.vanitycert.com
Wait 5-10 minutes for propagation
Test with dig or online tools

Best Practices

Before Adding Domain

✅ Configure DNS first, then add domain to VanityCert

This ensures immediate validation when domain is created.

TTL Settings

✅ Use low TTL (300 seconds / 5 minutes) during setup

This allows faster changes if you need to update the record.

✅ Increase TTL after validation (optional)

Once validated, you can increase to 3600 (1 hour) or higher for better DNS performance.

DNS Changes

✅ Test in staging first for production domains

✅ Monitor validation status after DNS changes

✅ Keep records simple - one CNAME per subdomain

Security

✅ Use DNSSEC if your provider supports it

✅ Restrict DNS access to authorized team members

✅ Monitor DNS changes with alerting tools

Advanced Configuration

Infrastructure as Code

Terraform Example:

variable "domains" {
  type = list(string)
  default = ["app", "api", "dashboard"]
}

resource "aws_route53_record" "vanitycert" {
  for_each = toset(var.domains)

  zone_id = aws_route53_zone.main.zone_id
  name    = "${each.key}.yourdomain.com"
  type    = "CNAME"
  ttl     = 300
  records = ["my.vanitycert.com"]
}

Pulumi Example (TypeScript):

const domains = ["app", "api", "dashboard"];

domains.forEach(subdomain => {
  new aws.route53.Record(`${subdomain}-vanitycert`, {
    zoneId: zone.id,
    name: `${subdomain}.yourdomain.com`,
    type: "CNAME",
    ttl: 300,
    records: ["my.vanitycert.com"],
  });
});

Automated DNS via API

Some DNS providers offer APIs for automated record management:

Cloudflare API:

curl -X POST "https://api.cloudflare.com/client/v4/zones/{zone_id}/dns_records" \
  -H "Authorization: Bearer {cloudflare_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "CNAME",
    "name": "app.yourdomain.com",
    "content": "my.vanitycert.com",
    "ttl": 300,
    "proxied": false
  }'

Route 53 API (via AWS SDK):

const AWS = require('aws-sdk');
const route53 = new AWS.Route53();

await route53.changeResourceRecordSets({
  HostedZoneId: 'Z1234567890ABC',
  ChangeBatch: {
    Changes: [{
      Action: 'CREATE',
      ResourceRecordSet: {
        Name: 'app.yourdomain.com',
        Type: 'CNAME',
        TTL: 300,
        ResourceRecords: [{ Value: 'my.vanitycert.com' }]
      }
    }]
  }
}).promise();

Next Steps

Once DNS is configured and validated:

Monitor Certificate Status - Track SSL provisioning progress
Set Up Webhooks - Receive notifications for certificate events
Configure Auto-Renewal - Ensure certificates renew automatically

See Also:

Overview​

Why CNAME Records?​

Quick Setup​

Step 1: Find Your Domain​

Step 2: Add CNAME Record​

Step 3: Verify DNS​

Provider-Specific Instructions​

Cloudflare​

AWS Route 53​

Google Cloud DNS​

GoDaddy​

Namecheap​

Vercel DNS​

DNS Propagation​

Validation Timeline​

Multiple Domains​

Wildcard Domains​

Apex Domains​

Option 1: Use Subdomain (Recommended)​

Option 2: ALIAS Record (DNS Provider Support Required)​

Troubleshooting​

DNS Not Validated After 30 Minutes​

Domain Stuck in "Pending" Status​

"CNAME Record Not Found" Error​

Best Practices​

Before Adding Domain​

TTL Settings​

DNS Changes​

Security​

Advanced Configuration​

Infrastructure as Code​

Automated DNS via API​

Next Steps​