Skip to main content
Start a Let’s Encrypt certificate request for a domain. This is Step 1 of the zero-downtime domain connection flow. Returns a TXT record that the user must add to their DNS to verify domain ownership.

​
Why Let’s Encrypt?

We use Let’s Encrypt instead of Amazon ACM because:
  • Universal compatibility: Let’s Encrypt is allowed by ALL DNS providers
  • No CAA conflicts: Some providers (Vercel, Netlify) have CAA records that block Amazon
  • Fast issuance: Certificates are issued in seconds after DNS verification

​
Path Parameters

ParameterTypeRequiredDescription
org_idstringYesClerk organization slug

​
Example Request

curl -X POST https://searchcompany-main.up.railway.app/api/domain/start-certificate/my-company-123456 \
  -H "Authorization: Bearer $TOKEN"

​
Example Response

{
  "txt_record_name": "_acme-challenge.www.example.com",
  "txt_record_value": "abc123xyz789...",
  "order_url": "https://acme-v02.api.letsencrypt.org/acme/order/...",
  "authorization_url": "https://acme-v02.api.letsencrypt.org/acme/authz/...",
  "challenge_url": "https://acme-v02.api.letsencrypt.org/acme/chall/...",
  "finalize_url": "https://acme-v02.api.letsencrypt.org/acme/finalize/..."
}

​
Response Fields

FieldTypeDescription
txt_record_namestringDNS TXT record name to add
txt_record_valuestringDNS TXT record value
order_urlstringACME order URL (for tracking)
authorization_urlstringACME authorization URL
challenge_urlstringACME challenge URL
finalize_urlstringACME finalize URL

​
What Happens Next

  1. User adds the TXT record via Entri
  2. Frontend calls /complete-certificate to validate and issue the cert
  3. Certificate is imported to ACM and attached to CloudFront
  4. User can then switch their www CNAME to CloudFront (zero downtime!)

​
Frontend Integration

// Step 1: Start certificate request
const certReq = await startCertificate(orgSlug, token);

// Step 2: Launch Entri with TXT record
const dnsRecords = [{
  type: "TXT",
  host: "_acme-challenge.www",  // extracted from txt_record_name
  value: certReq.txt_record_value,
  ttl: 300
}];
Entri.showEntri({ dnsRecords, ... });