Skip to main content
Get proxy information for an organization. Returns CloudFront distribution info and connection status needed for the two-part DNS configuration flow. Supports:
  • Apex domains (example.com)
  • WWW subdomains (www.example.com)
  • Custom subdomains (shop.example.com, blog.example.com, etc.)

​
Path Parameters

ParameterTypeRequiredDescription
org_idstringYesClerk organization slug (e.g., company-name-123456)

​
Example Request

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

​
Example Response (WWW Subdomain - Deployed)

{
  "has_proxy": true,
  "proxy_status": "DEPLOYED",
  "cloudfront_domain": "d123abc456def.cloudfront.net",
  "distribution_id": "E123ABC456",
  "certificate_arn": "arn:aws:acm:us-east-1:123456:certificate/abc-123",
  "origin_cname": "abc123.vercel-dns.com",
  "original_www_cname": "abc123.vercel-dns.com",
  "custom_domain": "www.example.com",
  "domain_type": "subdomain",
  "naked_domain": "example.com",
  "subdomain_label": "www",
  "apex_gateway_ips": null
}

​
Example Response (Custom Subdomain - shop.example.com)

{
  "has_proxy": true,
  "proxy_status": "DEPLOYED",
  "cloudfront_domain": "d123abc456def.cloudfront.net",
  "distribution_id": "E123ABC456",
  "certificate_arn": "arn:aws:acm:us-east-1:123456:certificate/abc-123",
  "origin_cname": "shop-origin.example.com",
  "original_www_cname": "shop-origin.example.com",
  "custom_domain": "shop.example.com",
  "domain_type": "subdomain",
  "naked_domain": "example.com",
  "subdomain_label": "shop",
  "apex_gateway_ips": null
}

​
Example Response (Apex Domain - Ready for Part 2)

{
  "has_proxy": true,
  "proxy_status": "SSL_VALIDATED",
  "cloudfront_domain": "d123abc456def.cloudfront.net",
  "distribution_id": "E123ABC456",
  "certificate_arn": "arn:aws:acm:us-east-1:123456:certificate/abc-123",
  "origin_cname": "104.20.22.37",
  "original_www_cname": null,
  "custom_domain": "example.com",
  "domain_type": "apex",
  "naked_domain": "example.com",
  "subdomain_label": "@",
  "original_apex_a_records": ["104.20.22.37", "172.66.165.95"],
  "apex_gateway_ips": ["15.197.156.92", "76.223.83.76"]
}

​
Example Response (No Proxy)

{
  "has_proxy": false,
  "proxy_status": null,
  "cloudfront_domain": null,
  "distribution_id": null,
  "certificate_arn": null,
  "origin_cname": null,
  "original_www_cname": null,
  "custom_domain": null,
  "domain_type": "subdomain",
  "naked_domain": null,
  "subdomain_label": null,
  "apex_gateway_ips": null
}

​
Response Fields

FieldTypeDescription
has_proxybooleanWhether a proxy has been set up
proxy_statusstringCurrent status in the flow (see below)
cloudfront_domainstringCloudFront distribution domain
distribution_idstringAWS CloudFront distribution ID
certificate_arnstringAWS ACM certificate ARN (set after Part 1 completes)
origin_cnamestringOriginal origin (CNAME or A record IP)
original_www_cnamestringOriginal CNAME before proxy (for subdomain disconnect)
custom_domainstringCustomer’s domain (e.g., www.example.com, shop.example.com, example.com)
domain_typestring"subdomain" or "apex"
naked_domainstringNaked domain (e.g., example.com)
subdomain_labelstringDNS record host: "www", "shop", "@" for apex
original_apex_a_recordsstring[]Original A records for apex (for apex disconnect)
apex_gateway_ipsstring[]Gateway IPs for apex domains (used in Part 2 A records)

​
Proxy Status Flow

PENDING_VALIDATION → SSL_VALIDATED → DEPLOYED
       ↓                   ↓              ↓
  Ready for          SSL cert        User completed
  Part 1             issued &        Part 2, fully
  (TXT record)       attached        operational
StatusDescriptionUI State
PENDING_VALIDATIONCloudFront created, ready for Part 1Show “Start SSL Validation” button
SSL_VALIDATEDSSL attached to CloudFront, ready for Part 2Show “Connect Domain” button
DEPLOYEDPart 2 done, domain connectedShow success state

​
Two-Part Flow (Works for All Domain Types)

Part 1: Domain Verification (no downtime)
  1. Frontend calls /start-certificate to get TXT record
  2. User adds TXT record via Entri
  3. Frontend calls /complete-certificate to validate and issue cert
  4. Let’s Encrypt certificate is attached to CloudFront
  5. Status becomes SSL_VALIDATED
Part 2: DNS Switch (zero downtime)
  • Subdomains (www, shop, blog): User adds CNAME subdomain_label → cloudfront_domain via Entri
  • Apex domains: User adds A @ → apex_gateway_ips via Entri (2 A records)

​
Domain Type Handling

Domain TypeExamplePart 2 Recordsubdomain_label
Apexexample.comA @ → Gateway IPs@
WWWwww.example.comCNAME www → CloudFrontwww
Shopshop.example.comCNAME shop → CloudFrontshop
Blogblog.example.comCNAME blog → CloudFrontblog
Multi-levelapi.v2.example.comCNAME api.v2 → CloudFrontapi.v2

​
Why Apex Domains Need Gateway IPs

Apex/naked domains (example.com) cannot use CNAME records per DNS specification. We provide static IP addresses via AWS Global Accelerator that route to our proxy, which then forwards to CloudFront. This works with ALL DNS providers (GoDaddy, Cloudflare, Vercel, Namecheap, etc.) because A records are universally supported.