# Cnamio developer docs > Cnamio lets the users of your product connect their own domain to it. You describe the DNS records your service needs; Cnamio finds where the user's DNS is hosted, creates the records when the provider allows it (with an API token the user pastes, used once and never stored) or shows the exact records to copy, then confirms them on the domain's authoritative nameservers and notifies your backend with a signed webhook. Existing DNS records are never deleted or overwritten; an existing SPF policy is only extended, keeping every term it has. - API: `https://api.cnamio.com` · Browser SDK: `https://connect.cnamio.com/sdk/v1.js` - OpenAPI 3.1: https://cnamio.com/openapi.json · MCP server: `https://api.cnamio.com/mcp` - Step-by-step guide for coding agents: https://cnamio.com/agent-onboarding/SKILL.md - Quickstart: https://cnamio.com/quickstart · DNS providers: https://cnamio.com/providers · Security: https://cnamio.com/security - Each integration is an **application** with an `applicationId` (`app_…`) and a secret (`cnm_sk_…`, shown once). Keep the secret on your server. Create a free account at https://cnamio.com/#start: you get a test application and a live application on the free plan, and you generate each secret in the dashboard. ## For AI agents To add custom domains to a project, read and follow https://cnamio.com/agent-onboarding/SKILL.md. It covers the records to choose, environment variables, the server session route, the browser connect window, a headless API flow (for agents and backends without a UI) and webhook verification, with Node.js and Python examples. The OpenAPI document describes every route and the webhook payload. ## Server SDKs One file each, no dependencies, for your backend (they hold the secret): [`cnamio.mjs`](https://cnamio.com/sdk/cnamio.mjs) for Node.js 18+ with types in [`cnamio.d.mts`](https://cnamio.com/sdk/cnamio.d.mts), and [`cnamio.py`](https://cnamio.com/sdk/cnamio.py) for Python 3.9+. Save the file in your project and import it. ```js import { Cnamio, recordsForUser, verifyWebhook } from './cnamio.mjs'; const cnamio = new Cnamio(); // CNAMIO_APPLICATION_ID and CNAMIO_SECRET from the environment const records = recordsForUser({ target: 'customers.yourapp.com', userId: user.id, ownershipKey: process.env.CNAMIO_OWNERSHIP_KEY }); const session = await cnamio.createSession({ userId: user.id, dnsRecords: records }); // for the connect window const job = await cnamio.connect('shop.customer.com', records, { userId: user.id }); // headless const ok = verifyWebhook(rawBody, headers, process.env.CNAMIO_WEBHOOK_SECRET); ``` ```python from cnamio import Cnamio, records_for_user, verify_webhook cnamio = Cnamio() records = records_for_user(target="customers.yourapp.com", user_id=user.id, ownership_key=os.environ["CNAMIO_OWNERSHIP_KEY"]) session = cnamio.create_session(user_id=user.id, dns_records=records) ``` Also: `checkDomain`, `connectAutomatic`, `status`, `recheck`, `lastWebhook` and `manage.jobs/usage/application/setWebhookUrl/webhookSecret/testWebhook/rotateSecret` (snake_case in Python). Errors are `CnamioError` with `status` and, on the 409 of `connectAutomatic`, `conflicts` (a list of reason codes such as `name_occupied`). The SDKs do not repeat a 503 on their own. ## MCP server Agents can also use Cnamio directly as tools through the MCP server at `https://api.cnamio.com/mcp` (Streamable HTTP). Tools: `get_integration_guide` (no credentials), `check_domain`, `connect_domain`, `connect_domain_automatic`, `get_connection_status`, `recheck_propagation`, `list_connections`, `create_share_link` and `revoke_share_link`. They behave exactly like the REST routes (same validation, limits and allowed targets). Authenticate with the application credentials as HTTP Basic (or a session token as `Bearer` plus an `applicationId` header): ```bash # Claude Code claude mcp add --transport http cnamio https://api.cnamio.com/mcp \ --header "Authorization: Basic $(printf '%s' "$CNAMIO_APPLICATION_ID:$CNAMIO_SECRET" | base64 | tr -d '\n')" ``` ```json { "mcpServers": { "cnamio": { "url": "https://api.cnamio.com/mcp", "headers": { "Authorization": "Basic " } } } } ``` Keep this configuration out of version control: it carries the application secret. ## 1. Create a session token on your server ```bash curl -X POST https://api.cnamio.com/token \ -H 'Content-Type: application/json' \ -d '{ "applicationId": "app_…", "secret": "cnm_sk_…", "userId": "user-42" }' # → 200 { "auth_token": "eyJ…" } ``` The token is valid for 60 minutes. Optional `domain`, `userId` and `dnsRecords` are bound to the session: a session created with a domain or a record list can only be used for exactly those, and one created with a `userId` answers 403 to a different `userId` in a call. `/token` never answers browser (CORS) requests. ## 2. Open the connect window in your page ```html ``` The window runs in an iframe from our origin with its own Content-Security-Policy; the configuration (token included) reaches it only through `postMessage`, never in a URL. Also available: `cnamio.close()` and `cnamio.checkDomain(domain, config)`. Use `forceManualSetup: true` (with `prefilledDomain`) to always show the copy-the-records steps, and `primaryColor: '#2156f0'` to match your brand. Step names in `onCnamioStepChange`: `ENTER_DOMAIN`, `DOMAIN_ANALYSIS`, `LOGIN`, `EXISTING_RECORDS`, `MANUAL_CONFIGURATION`, `WAITING_PROPAGATION`, `FINISHED_SUCCESSFULLY`, `FINISHED_SUCCESSFULLY_MANUAL`. ## DNS records Each record has `type` (`A`, `AAAA`, `CNAME`, `TXT`, `MX`, `CAA`), `host`, `value`, optional `ttl` (default 300), `priority` (MX) and `optional`. Placeholders in `host` and `value`: `{DOMAIN}` (the domain's real DNS zone, for example `meustudio.com.br`), `{SUBDOMAIN}` (everything left of the zone: `agenda` for `agenda.meustudio.com.br`, `a.b` for `a.b.x.com.br` in zone `x.com.br`), `{SLD}`, `{TLD}` (`meustudio`, `com.br`); `@` is the zone apex. Other `{…}` tokens are refused. Up to 20 records per connection. **Prove ownership per user.** If all your users point their domains at the same CNAME target, a CNAME that already exists proves nothing about who started the connection: another user of your app could claim a domain that is already pointed at you. Add a required TXT record whose value is unique to each user (for example an HMAC of the user id with a secret of yours), built on your server and bound to the session token, such as `{ "type": "TXT", "host": "_yourapp-verify.{SUBDOMAIN}", "value": "yourapp-verify=" }`. `domain.added` is sent only when every required record is live. Automatic setup (the user pastes an API token or key, used once and never stored) works with Cloudflare, Hostinger and Amazon Route 53; every other provider gets the exact records to copy (with `locale: "pt-BR"`, also the steps in the detected provider's panel). Details per provider: https://cnamio.com/providers **Existing records are never deleted.** A CNAME needs a free name; A, AAAA and MX are never added next to different existing values (an existing MX is never replaced); TXT and CAA values are added next to existing ones, except a second DMARC policy (`dmarc_exists`) or a second DKIM key at the same selector (`dkim_selector_exists`). When something is in the way, the user sees what already exists and decides. **Email records.** A domain can publish only one SPF policy, so a requested SPF is merged into the existing one instead of becoming a second record: every existing term is kept as it is, in its place, including the `all` qualifier, and only the missing mechanisms are added just before `all`. If the existing policy already authorizes them, nothing is written and the record counts as present. The merge is refused, with a reason, when the name has more than one SPF policy (`spf_multiple_records`), the request has two (`spf_multiple_requested`), the existing policy cannot be read safely (`spf_unparseable`), the requested one has modifiers such as `redirect=` (`spf_merge_unsupported`), or the result would pass 10 DNS-lookup terms (`spf_lookup_limit`, counted on the merged record itself) or 450 characters (`spf_too_long`). With `checkConflicts`, `/checkdomain` returns `recordMerges` with the full merged value and the policy it replaces; the connect window asks the user to edit the existing record with that value. Unless the request sends `acceptMerges: true`, each merge is also listed in `recordConflicts` as `spf_merge_required`, with the merged value in `merge`, so a client that builds its own instructions never asks for a second SPF record. `POST /connect` returns the same `recordMerges`, and `merge` on the SPF record. The automatic path answers `409` with `spf_merge_required` unless the merge is enabled for that DNS provider, and Domain Connect is not offered when a merge is needed. A connection with an SPF record is verified (and monitored) when the name has exactly one policy authorizing the requested mechanisms. ## REST endpoints Send `Authorization: Bearer ` and `applicationId: app_…`. These endpoints answer CORS, so they can be called from your page with the session token. | Endpoint | What it does | | --- | --- | | `POST /checkdomain` | `{ domain, dnsRecords, checkConflicts? }` → DNS provider, `setupType` (`Automatic` or `Manual`), `connectMethods`, nameservers, `records` (every record that would be created, with its full name) and, when asked, `recordConflicts` with what is already published and `recordMerges` with SPF policies that will be merged into the existing one. For a single CNAME at the domain it also returns `recordState` (`missing`, `configured`, `different_cname`, `name_occupied` or `inconclusive`), read from the domain's authoritative nameservers. | | `POST /connect` | Manual setup: returns the records exactly as they should be created and starts watching propagation. `201 { job_id, … }` | | `POST /connect/automatic` | `{ domain, dnsRecords, providerToken }`: creates the records with the user's provider token (used once, not stored). `201`, `409 { conflicts }` or `422` when the provider refuses the token. | | `GET /connect/{jobId}/status` | `{ connected, status, propagation_status, setup_type, health, monitored, health_changed_at, health_checked_at, missing_records }` (the last five: see Monitoring) | | `POST /connect/propagation/recheck/{jobId}` | Checks again now; at most once every 5 minutes (`429`). Only for jobs still in progress: a finished job answers `409`. | | `GET /connect/webhooks/last/{jobId}` | The last webhook of a connection and its delivery state. | Propagation is checked on every authoritative nameserver: every 10 seconds for the first 2 minutes, then at growing intervals (up to one hour apart), for up to 72 hours. ## Webhooks Set the URL in the dashboard (or `PUT /v1/manage/webhook`). Events: `domain.added` when every required record is live, `domain.propagation.timeout` after 72 hours without it, `domain.records_missing` and `domain.records_restored` from monitoring (below), and `webhook.test` when you send a test. Ignore event types you do not handle: new ones may be added. Payload fields include `id`, `type`, `job_id`, `user_id`, `domain`, `subdomain`, `provider`, `setup_type`, `propagation_status` and `data.records_propagated` / `records_non_propagated`. Every request carries `Cnamio-Timestamp` (unix seconds), `Cnamio-Event-Id` and `Cnamio-Signature: sha256=`, an HMAC-SHA256 of `"{timestamp}.{raw body}"` with your signing secret (dashboard → Webhook → Reveal secret, or `GET /v1/manage/webhook-secret`). Reject timestamps older than 5 minutes. ```js import { createHmac, timingSafeEqual } from 'node:crypto'; function verifyCnamio(rawBody, headers, secret) { const tsHeader = String(headers['cnamio-timestamp'] ?? ''); const ts = Number(tsHeader); if (!secret || !Number.isFinite(ts) || Math.abs(Date.now() / 1000 - ts) > 300) return false; const expected = Buffer.from('sha256=' + createHmac('sha256', secret).update(`${tsHeader}.${rawBody}`).digest('hex')); const given = Buffer.from(String(headers['cnamio-signature'] ?? '')); return given.length === expected.length && timingSafeEqual(given, expected); } ``` Verify over the raw body (in Express, register the webhook route with `express.raw()` before any global `express.json()`). Answer `2xx` only after storing the result: other answers are retried after 1, 5 and 30 minutes (four attempts in all), and after that the state stays readable at `GET /connect/{jobId}/status`, so reconcile pending domains periodically. Changing the webhook URL does not change the signing secret. Webhook URLs must be public HTTPS addresses; redirects are not followed. ## Monitoring Included, with no extra charge per domain: after a domain connects, Cnamio keeps asking its authoritative nameservers for the same records, every hour on the first day, every 6 hours for the rest of the first week and once a day after that. Monitoring only reads DNS; it never creates, changes or removes a record. Each connection has a `health`: `healthy` (every record is where it was), `degraded` (the required records are there, but an optional record that was published is gone, or the zone could not be read for several checks in a row) or `broken` (a required record is gone). A change is confirmed by a second check a few minutes later before it counts, and then your webhook receives `domain.records_missing` (health became `degraded` or `broken`) or `domain.records_restored` (back to `healthy`), signed like every other event. The payload has the fields of `domain.added` plus `health`, `previous_health`, `reason` (`records_missing`, `dns_unreachable` or `records_restored`) and `data.records_missing`. The state is also in `GET /connect/{jobId}/status`, in `GET /v1/manage/jobs` (filter with `health=broken`) and in the dashboard. Monitoring is a setting of the application (dashboard → Monitoring, or `PUT /v1/manage/monitoring`): on for new applications; applications created before it existed turn it on there. When a domain is connected again, the newest connection is the one monitored. A domain that stays `broken` for 30 days stops being monitored. Each application has a cap of monitored domains (`monitor_limit` in `GET /v1/manage/application`). ## Shareable connection links When the person who manages the DNS is not your user (an agency, a freelancer, the IT team), create a link on your server and send it to them. They open it, see the domains your user asked for and run the same connect window (automatic, provider consent or step-by-step records) for each one. They never see your secret and need no account. ```bash curl -s https://api.cnamio.com/v1/manage/share-links -u "$CNAMIO_APPLICATION_ID:$CNAMIO_SECRET" \ -H 'Content-Type: application/json' \ -d '{"domains":["shop.customer.com"],"dnsRecords":[{"type":"CNAME","host":"{SUBDOMAIN}","value":"customers.yourapp.com"}],"userId":"42"}' # → 201 { "share_link_id": "shl_…", "url": "https://api.cnamio.com/s/cnsl_…", "status": "active", "expires_at": "…", … } ``` - The link is bound to those domains, those records and that `userId`: it cannot connect anything else. - `maxUses` (default 1) is how many connections each domain may start through it; `expiresInDays` defaults to 7 and is at most 30. A flow abandoned before a connection starts (window closed, conflict, refused token) uses nothing. - `url` (and its `token`) is returned only in this answer; the token is stored only as a hash. Send the URL to the person; do not log it. - `POST /v1/manage/share-links/{id}/revoke` ends it at once; a revoked or expired link answers 410 on its page, and sessions it already handed out stop starting connections. - Connections started through it are ordinary connections: same status routes and webhooks, with `share_link_id` added to the job and to the webhook payload. `GET /v1/manage/jobs?share_link_id=` lists them. - Also in the dashboard (Connection links), the server SDKs (`createShareLink`, `create_share_link`) and the MCP tool `create_share_link`. ## Management API (your server only) HTTP Basic authentication with `applicationId:secret`. These routes never answer CORS. | Endpoint | What it does | | --- | --- | | `GET /v1/manage/application` | Name, webhook URL and settings of the application. | | `PUT /v1/manage/webhook` | `{ url }` (HTTPS) or `null` to stop deliveries. | | `PUT /v1/manage/record-names` | `{ strict?, allowedNames? }`: strict record names. When on (the default for new applications), every record must be at the connected hostname or under it; names elsewhere in the zone must be listed here, relative to the zone (`@`, `_dmarc`). Otherwise the request answers 403. | | `PUT /v1/manage/monitoring` | `{ enabled }`: turns continuous monitoring on (the domains already connected start being monitored too) or off. Returns `{ monitoring, monitor_limit, monitored_domains }`. | | `GET /v1/manage/webhook-secret` | The secret that signs your webhooks. | | `POST /v1/manage/webhook-test` | Sends a signed `webhook.test`; returns `{ delivered, status }`. | | `POST /v1/manage/rotate-secret` | `{ graceHours? }`: new secret (shown once); the old one keeps working for the grace period (default 24 h). | | `GET /v1/manage/jobs` | Recent connections, newest first (`limit`, `before`, `status`, `domain`, `health`, `share_link_id`), each with its monitoring state. | | `POST /v1/manage/share-links` | `{ domains, dnsRecords, maxUses?, expiresInDays?, userId?, label? }`: a shareable connection link; returns its `url` once. | | `GET /v1/manage/share-links` · `GET …/{id}` · `POST …/{id}/revoke` | List (never the tokens), read, revoke. | | `GET /v1/manage/usage?month=YYYY-MM` | Connections started, completed and expired, and billable domains: each connected domain counts once per month. | ## Test applications and plans A self-service account has two applications. The **test** application runs every route against a sandbox provider: any domain name works, nothing is read from or written to real DNS, connections complete on the first propagation check and webhooks are delivered and signed as usual. `/checkdomain` answers `provider: "sandbox"` and `sandbox: true`; any non-empty provider token is accepted except `invalid` (answered 422). A domain whose first label is `conflict` (`conflict.shop.example.com`) has a foreign CNAME at every name (409 on the automatic connection); one starting with `pending` never shows its records (the job times out after 72 h). Test applications start up to 100 domains per month (then 429 with `code: "sandbox_limit_reached"`). The **live** application has a plan with a monthly allowance of connections: distinct domains whose connection starts in the UTC calendar month and does not time out (starting the same domain again that month is free; checking, monitoring and webhooks never count). Over the allowance, the routes that start a connection (`POST /connect`, `/connect/automatic`, `/connect/domainconnect`) answer **402** with `{ message, code: "plan_limit_reached", plan, limit, used, resets_at }` and a `Retry-After` until the month turns; domains already connected keep working and being monitored. At 80% the account's people get an email and your webhook gets one signed `usage.quota_warning` event (`{ id, type, application_id, job_id, plan, month, limit, used, remaining, threshold, resets_at, created_at }`). `GET /v1/manage/application` and `GET /v1/manage/usage` include `mode`, `plan` and `quota` (`null` when no cap applies). Plans: https://cnamio.com/pricing. ## Errors and limits Errors are `{ "message": "…" }` with a fixed text; request contents are never echoed back. Usual statuses: 400 invalid input, 401 invalid credentials or session, 403 session not valid for this domain or records, 404, 409 conflict with existing DNS (on recheck: the connection is already finished), 422 provider refused, 503 not now (the domain's DNS answered too slowly or the service is busy; nothing was written, repeat the same request after the seconds in `Retry-After`), 429 too many requests (by default 60 per minute per address and per session, under a ceiling of 600 per application; a backend that calls on behalf of many end users from one address can ask for a per-application limit, which then is the only one applied to its sessions). Session tokens last 60 minutes; reuse them, and ask your server for a new one when needed. Binding `dnsRecords` to a session compares the whole array exactly (`ttl` included), so return the bound array from your server and pass it to the window unchanged. `userId` is optional, up to 128 characters, and comes back as `user_id` (or `null`). Content-Security-Policy for the page that opens the window: `script-src` and `frame-src` `https://connect.cnamio.com` (plus `connect-src` if you call `cnamio.checkDomain` in the browser). Cnamio never deletes DNS records: after `failed`, or for another domain, start a new connection; to disconnect, stop serving the domain in your app. Questions or access: contato@cnamio.com · Privacy: https://cnamio.com/privacy · Terms: https://cnamio.com/terms