You will need a Cnamio application. Create a free account with your email: you get a test application, which connects any domain against a simulated provider without touching real DNS, and a live application on the free plan. Generate each one's secret in the dashboard. Questions: contato@cnamio.com.
01Add your credentials
An application has an id and a secret. The secret is shown once; keep it in your server's environment and add only the variable names to .env.example.
CNAMIO_APPLICATION_ID=app_… # not secret
CNAMIO_SECRET=cnm_sk_… # server only, never committed
CNAMIO_OWNERSHIP_KEY=… # any long random secret of yours (step 3)
CNAMIO_WEBHOOK_SECRET=… # from step 5
02Add the server SDK
One file, no dependencies. Save it in your project and commit it.
# Node.js 18+: one file plus its types, no dependencies
mkdir -p lib
curl -s https://cnamio.com/sdk/cnamio.mjs -o lib/cnamio.mjs
curl -s https://cnamio.com/sdk/cnamio.d.mts -o lib/cnamio.d.mts
# Python 3.9+: standard library only
curl -s https://cnamio.com/sdk/cnamio.py -o cnamio.py
Prefer plain HTTP? Every call below is one request; see the REST reference or the OpenAPI document.
03Create a session on your server
After authenticating your own user, ask Cnamio for a session token bound to the records that user must create. recordsForUser builds a CNAME to your hosting plus an ownership TXT unique to the user, so nobody else can claim the same domain.
import { Cnamio, recordsForUser } from './lib/cnamio.mjs';
const cnamio = new Cnamio(); // reads CNAMIO_APPLICATION_ID and CNAMIO_SECRET
app.post('/api/cnamio/session', requireUser, async (req, res) => {
// A CNAME to your hosting plus a TXT only this user can satisfy.
const dnsRecords = recordsForUser({
target: 'customers.yourapp.com',
userId: req.user.id,
ownershipKey: process.env.CNAMIO_OWNERSHIP_KEY,
});
res.json(await cnamio.createSession({ userId: req.user.id, dnsRecords }));
});
import os
from fastapi import Depends
from cnamio import Cnamio, records_for_user
cnamio = Cnamio() # reads CNAMIO_APPLICATION_ID and CNAMIO_SECRET
@app.post("/api/cnamio/session")
def cnamio_session(user=Depends(current_user)):
# A CNAME to your hosting plus a TXT only this user can satisfy.
records = records_for_user(
target="customers.yourapp.com",
user_id=user.id,
ownership_key=os.environ["CNAMIO_OWNERSHIP_KEY"],
)
return cnamio.create_session(user_id=user.id, dns_records=records)
The session lasts 60 minutes. Because the records are bound to it, the browser cannot change the target or the ownership value.
04Open the connect window
Load the browser SDK once and open the window from the place where your users manage their domain.
<script src="https://connect.cnamio.com/sdk/v1.js"></script>
<script src="/js/custom-domain.js"></script>
// /js/custom-domain.js
async function connectCustomDomain() {
const r = await fetch('/api/cnamio/session', { method: 'POST' });
if (!r.ok) throw new Error('Custom domains are unavailable right now.');
const session = await r.json(); // { token, applicationId, dnsRecords, … }
window.cnamio.connectDomain({ ...session, applicationName: 'Your App', locale: 'en' });
}
window.addEventListener('onCnamioSuccess', e => {
// Not connected yet: save e.detail.domain as "pending" with e.detail.jobId.
});
Your user types the domain; Cnamio finds the DNS provider and either creates the records with a token they paste or shows the exact records to copy (how each provider works). If your page has a Content-Security-Policy, allow https://connect.cnamio.com in script-src and frame-src. Options such as locale (en, pt-BR, es), prefilledDomain and primaryColor are in the docs.
Apex domains. DNS does not allow a CNAME at mybrand.com itself. Ask users for a subdomain such as shop.mybrand.com, or send A/AAAA records with host @ if your hosting has fixed addresses.
05Receive the webhook
The browser event only says the flow ended. The webhook is the source of truth: domain.added arrives when every required record is live on the domain's nameservers, domain.propagation.timeout after 72 hours without it. After that the domain keeps being monitored (included): domain.records_missing and domain.records_restored tell you when its records disappear or come back; ignore them if you do not need them. Register your URL once (it must be public HTTPS):
curl -s -X PUT https://api.cnamio.com/v1/manage/webhook \
-u "$CNAMIO_APPLICATION_ID:$CNAMIO_SECRET" -H 'Content-Type: application/json' \
-d '{"url":"https://yourapp.com/webhooks/cnamio"}'
# The signing secret → CNAMIO_WEBHOOK_SECRET
curl -s -u "$CNAMIO_APPLICATION_ID:$CNAMIO_SECRET" https://api.cnamio.com/v1/manage/webhook-secret
Then verify the signature over the raw body before trusting the event:
import { verifyWebhook } from './lib/cnamio.mjs';
// Register this route before any global express.json(): the signature covers the raw body.
app.post('/webhooks/cnamio', express.raw({ type: 'application/json' }), (req, res) => {
const raw = req.body.toString('utf8');
if (!verifyWebhook(raw, req.headers, process.env.CNAMIO_WEBHOOK_SECRET)) return res.sendStatus(401);
const event = JSON.parse(raw);
if (event.type === 'domain.added') markDomainConnected(event.user_id, event.domain, event.job_id);
if (event.type === 'domain.propagation.timeout') markDomainFailed(event.user_id, event.domain, event.job_id);
res.sendStatus(200); // after storing; the same event.id can arrive again
});
import json, os
from fastapi import Request, Response
from cnamio import verify_webhook
@app.post("/webhooks/cnamio")
async def cnamio_webhook(request: Request):
raw = await request.body()
if not verify_webhook(raw, request.headers, os.environ.get("CNAMIO_WEBHOOK_SECRET")):
return Response(status_code=401)
event = json.loads(raw)
# Idempotent by event["id"]: mark event["user_id"] / event["domain"] connected or failed.
return Response(status_code=200)
Cnamio handles DNS only. If your hosting has to know each new hostname or issue a certificate for it, do that in your own code when domain.added arrives.
06Check it end to end
- Calling your session route as a signed-in user returns a token, and
cnm_sk_appears nowhere in your client bundle. - A test delivery reaches your endpoint and passes the signature check:
# A signed webhook.test reaches your endpoint → { "delivered": true, "status": 200 }
curl -s -X POST -u "$CNAMIO_APPLICATION_ID:$CNAMIO_SECRET" https://api.cnamio.com/v1/manage/webhook-test
- Connect a test subdomain of a domain you own, wait for
domain.added, then remove the records at your provider.
No user interface?
Everything the window does is available to a backend, a CLI or an agent: checkDomain, connect or connectAutomatic, then status, in both SDKs and over REST. The agents page shows the flow, and the docs list every route.