Getting Started

Welcome to VanityCert! This guide will help you get started with automated SSL certificate management for your custom domains.

Overview

VanityCert provides automated SSL/TLS certificate provisioning for your custom domains. Once you add a domain and configure DNS, VanityCert handles:

DNS Validation - Verifying domain ownership
Certificate Issuance - Requesting and provisioning SSL certificates
Certificate Monitoring - Tracking certificate status and expiry
Automatic Renewals - Renewing certificates before expiration
Webhook Notifications - Real-time alerts for certificate events

Quick Start

1. Create an API Key

First, create an API key to authenticate your requests:

Log in to your VanityCert dashboard
Navigate to Developer → API Keys
Click Create API Key
Give it a name (e.g., "Production") and select permissions
Copy your API key - you won't see it again!

Example API Key:

Public Key ID: vc_pk_abc123def456
Secret Key: sk_1234567890abcdef1234567890abcdef

2. Add a Domain

Use the API to add your domain:

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
  }'

Response:

{
  "id": 456,
  "url": "app.yourdomain.com",
  "dns_status": "pending",
  "ssl_status": "pending",
  "created_at": "2025-01-01T12:00:00Z"
}

3. Configure DNS

Add a CNAME record for your domain pointing to VanityCert:

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

DNS Provider Examples:

Cloudflare:

Type: CNAME
Name: app (or your subdomain)
Target: my.vanitycert.com
Proxy status: DNS only (grey cloud)

Route 53:

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"}]
      }
    }]
  }'

GoDaddy:

Host: app
Points to: my.vanitycert.com
TTL: 1 Hour
Type: CNAME

4. Wait for Certificate Provisioning

VanityCert will automatically:

Validate DNS (typically 5-30 minutes)
- Checks for CNAME record
- Retries every 5 minutes for up to 24 hours
Request Certificate (1-5 minutes)
- Submits request to certificate authority
- Performs HTTP challenge validation
Activate Certificate (1-5 minutes)
- Installs certificate on your server
- Updates status to active

Total Time: Usually 15-45 minutes, depending on DNS propagation.

5. Monitor Status

Check domain status 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"

Response:

{
  "id": 456,
  "url": "app.yourdomain.com",
  "dns_status": "validated",
  "ssl_status": "active",
  "renews_on": "2025-04-01",
  "last_renewed": "2025-01-01T12:30:00Z"
}

6. Set Up Webhooks (Optional)

Receive real-time notifications for certificate events:

curl -X POST https://app.vanitycert.com/api/webhooks \
  -H "X-API-KEY-ID: vc_pk_abc123def456" \
  -H "X-API-KEY: sk_1234567890abcdef1234567890abcdef" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://api.yourdomain.com/webhooks/vanitycert",
    "events": [
      "certificate.issued",
      "certificate.expired",
      "domain.created"
    ],
    "secret": "your-webhook-secret-key"
  }'

See Webhooks Guide for implementation details.

Authentication

All API requests require two headers for authentication:

X-API-KEY-ID: vc_pk_abc123def456
X-API-KEY: sk_1234567890abcdef1234567890abcdef

API Key Components:

Public Key ID (X-API-KEY-ID): Starts with vc_pk_ - Used to identify your API key (safe to log)
Secret Key (X-API-KEY): Starts with sk_ - Your private authentication key (keep secret)
Both headers are required for all API requests

Security Best Practices:

Never commit API keys to source control
Use environment variables to store both keys
Never expose the secret key in frontend/browser code
Use a backend proxy for widget integrations
Rotate keys regularly
Use separate keys for dev/staging/production

Base URL

All API requests use the base URL:

https://app.vanitycert.com/api

Rate Limits

Current Limits:

1000 requests per hour per organization
100 requests per minute per API key

Rate Limit Headers:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1704118800

When rate limited, you'll receive a 429 Too Many Requests response.

Common Workflows

Bulk Domain Creation

Add multiple domains at once:

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},
      {"url": "app3.yourdomain.com", "server_id": 123}
    ]
  }'

Check Certificate 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"

List Expiring Certificates

# Domains expiring in next 30 days
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"

SDKs & Libraries

PHP

<?php

use VanityCert\Client;

$client = new Client('vc_live_...');

// Add domain
$domain = $client->domains->create([
    'url' => 'app.yourdomain.com',
    'server_id' => 123
]);

// Check status
$domain = $client->domains->get(456);
echo "SSL Status: " . $domain->ssl_status;

// List domains
$domains = $client->domains->list(['ssl_status' => 'active']);

Node.js

const VanityCert = require('vanitycert');

const client = new VanityCert('vc_live_...');

// Add domain
const domain = await client.domains.create({
  url: 'app.yourdomain.com',
  server_id: 123
});

// Check status
const status = await client.domains.get(456);
console.log('SSL Status:', status.ssl_status);

// List domains
const domains = await client.domains.list({ ssl_status: 'active' });

Python

from vanitycert import Client

client = Client('vc_live_...')

# Add domain
domain = client.domains.create(
    url='app.yourdomain.com',
    server_id=123
)

# Check status
domain = client.domains.get(456)
print(f'SSL Status: {domain.ssl_status}')

# List domains
domains = client.domains.list(ssl_status='active')

Dashboard Access

In addition to the API, you can manage domains through the web dashboard:

URL: https://app.vanitycert.com/dashboard

Features:

View all domains and their status
Monitor certificate expiry dates
View detailed audit logs
Manage API keys and webhooks
View analytics and reports

Support

Documentation: https://docs.vanitycert.com

API Reference: https://app.vanitycert.com/api/docs

Support Email: support@vanitycert.com

Status Page: https://status.vanitycert.com

Next Steps

Now that you're set up, explore these guides:

DNS Configuration - Detailed DNS setup instructions
SSL Certificate Lifecycle - How certificate provisioning works
Webhooks - Receive real-time event notifications
Error Handling - Troubleshooting common issues

API Reference

For complete API documentation including all endpoints, request/response formats, and error codes, see:

OpenAPI Specification: Docs

The API reference is auto-generated from our OpenAPI specification and includes:

All available endpoints
Request/response schemas
Authentication requirements
Error codes and responses
Interactive API explorer

Overview​

Quick Start​

1. Create an API Key​

2. Add a Domain​

3. Configure DNS​

4. Wait for Certificate Provisioning​

5. Monitor Status​

6. Set Up Webhooks (Optional)​

Authentication​

Base URL​

Rate Limits​

Common Workflows​

Bulk Domain Creation​

Check Certificate Status​

List Expiring Certificates​

SDKs & Libraries​

PHP​

Node.js​

Python​

Dashboard Access​

Support​

Next Steps​

API Reference​