# From zero to a connected domain.

Six steps with the one-file server SDK: credentials, a session route, the connect window and a verified webhook. Your secret never leaves your server, and your backend learns that a domain is live from a signed event.

Free plan, no card · questions: [contato@cnamio.com](mailto:contato@cnamio.com)

You will need a Cnamio application. [Create a free account](https://cnamio.com/#start) 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](mailto:contato@cnamio.com).

## Or let your coding agent do it

Paste this into Claude Code, Cursor, Codex, Copilot or any coding agent, in the project where users should connect a domain. It follows the same six steps, and without an account it starts in the sandbox and asks before signing you up:

**English**

```
Add custom domains for my users with Cnamio: read and follow https://cnamio.com/agent-onboarding/SKILL.md. If I don't have a Cnamio account yet, start in the sandbox right away and ask me before signing me up for a free account with my email.
```

**Português**

```
Adicione domínio próprio para os usuários deste app com o Cnamio: leia e siga https://cnamio.com/agent-onboarding/SKILL.md. Se eu ainda não tiver conta no Cnamio, comece já no sandbox e me pergunte antes de criar uma conta gratuita com o meu e-mail.
```

**Español**

```
Agrega dominios propios para los usuarios de esta app con Cnamio: lee y sigue https://cnamio.com/agent-onboarding/SKILL.md. Si todavía no tengo cuenta en Cnamio, empieza ya en el sandbox y pregúntame antes de crear una cuenta gratuita con mi correo.
```

## 01. Add 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
```

## 02. Add the server SDK

One file, no dependencies. Save it in your project and commit it.

**Node.js**

```
# 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**

```
# 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](https://cnamio.com/docs#rest) or the [OpenAPI document](https://cnamio.com/openapi.json).

## 03. Create 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.

**Node.js (Express)**

```
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 }));
});
```

**Python (FastAPI)**

```
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.

## 04. Open 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](https://cnamio.com/providers)). 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](https://cnamio.com/docs#sdk).

**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.

## 05. Receive 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:

**Node.js (Express)**

```
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
});
```

**Python (FastAPI)**

```
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.

## 06. Check it end to end

1. Calling your session route as a signed-in user returns a token, and `cnm_sk_` appears nowhere in your client bundle.
2. 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
```

1. 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](https://cnamio.com/agents#headless) shows the flow, and the [docs](https://cnamio.com/docs) list every route.

---

This is the Markdown of https://cnamio.com/quickstart. Every page for agents: https://cnamio.com/llms.txt
