# Cnamio: the whole documentation in one file > Every document for agents at https://cnamio.com, one after another. The index is https://cnamio.com/llms.txt; each part is also served on its own at the URL in its heading. # 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 Prompt for your coding agent (paste it in the project): ```text 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. ``` In Portuguese: "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." In Spanish: "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." 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. ## Agent onboarding: sandbox and sign-up Two routes let a coding agent start before its developer has an account. Both take no credentials and refuse requests from a browser (an `Origin` header gets `403`). - `POST /v1/agent/sandbox` (no body) → `201 { application_id, auth_token, expires_at, user_id, mode: "test", sandbox: true }`: a 30-minute session of a Cnamio test application. Use it as `Bearer` with the `applicationId` header on `/checkdomain`, `/connect`, `/connect/automatic` and `/connect/{jobId}/status`; it sees only the connections it started. Any domain connects; `conflict.` and `pending.` prefixes and the provider token `invalid` simulate failures. No real DNS is read or written. - `POST /v1/agent/signup` `{ email, consent: true, name?, company?, locale?, client?: { name, version } }` → `202 { received, message, next_steps, sandbox? }`: emails the developer the same link as the site's sign-up. Opening it creates the free account (a test application and a live one on the free plan); nothing exists before. `consent` means the developer agreed to the Terms (https://cnamio.com/terms) and the Privacy Policy (https://cnamio.com/privacy); without it the answer is `400`. The answer is the same for a new address and a known one. Limits: a sandbox session 5 times a minute and 20 times a day per address; a sign-up 3 times a minute and 10 times a day per address, and at most one email per address per 15 minutes (4 a day). Over a limit: `429`. ## MCP server Agents can also use Cnamio directly as tools through the MCP server at `https://api.cnamio.com/mcp` (Streamable HTTP). Without credentials: `get_integration_guide`, `start_sandbox` (a sandbox session the domain tools take as `sandboxToken`) and `start_signup` (a free account for the developer, verified by email). With 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). In claude.ai and ChatGPT, add `https://api.cnamio.com/mcp` as a connector: it signs you in with OAuth 2.1 (your account email), you pick the application and approve the permissions `domains:read`, `domains:write` and `share_links:write`, and revoke it any time under Connected agents in the dashboard (https://cnamio.com/agents#connectors). Discovery: `https://api.cnamio.com/.well-known/oauth-protected-resource/mcp` (PKCE S256, Client ID Metadata Documents and dynamic registration). Elsewhere, 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 450 characters (`spf_too_long`) or 10 DNS lookups (`spf_lookup_limit`). Lookups are counted over the whole evaluation of the merged policy, nested `include:` and `redirect=` targets read from public DNS; when they cannot be counted (a macro, a failed lookup, a target without exactly one policy) the merge is refused with `spf_lookup_unverified`. 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 requested SPF lands on a name that already publishes a different policy, even one that already covers the request (the provider would add a second one); for callers without `acceptMerges`, such a covering policy is also listed as `spf_merge_required`, with the existing policy as the value to keep. 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: contato@cnamio.com · Privacy: https://cnamio.com/privacy · Terms: https://cnamio.com/terms # 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. ``` ``` ``` // /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 # Cnamio: custom domains for your users Cnamio connects your users' own domains (for example `shop.customer.com`) to your product. Your user types the domain; Cnamio finds where its DNS lives, creates the records your product needs when the provider allows it (with an API token the user pastes, used once and never stored) or shows the exact records to copy, confirms them on the domain's authoritative nameservers and notifies your backend. Existing DNS records are never deleted or overwritten; an existing SPF policy is only extended, keeping every term it has. - API base: `https://api.cnamio.com` · Browser SDK: `https://connect.cnamio.com/sdk/v1.js` · MCP server: `https://api.cnamio.com/mcp` - OpenAPI: `https://cnamio.com/openapi.json` · Full docs (Markdown): `https://cnamio.com/docs.md` · Everything in one file: `https://cnamio.com/llms-full.txt` - Server SDKs, no dependencies: `npm i cnamio` (Node.js 18+, typed) and `pip install cnamio` (Python 3.9+). The same single files are served at `https://cnamio.com/sdk/cnamio.mjs` (types in `cnamio.d.mts`) and `https://cnamio.com/sdk/cnamio.py` for projects that vendor them. - Framework recipes: `https://cnamio.com/recipes/nextjs.md`, `express.md`, `rails.md`, `laravel.md`, `django.md` (same base URL) - Credentials: an application id (`app_…`) and a secret (`cnm_sk_…`). Ask the project owner for them; if they have no account, see step 0. Build and test against the test application first. Never invent or hard-code them. ## 0. No account yet: sandbox now, free account by email You can take the developer from zero to a working integration in this session: 1. **Sandbox at once, no account.** `POST https://api.cnamio.com/v1/agent/sandbox` (no body or an empty JSON one, no credentials; or the MCP tool `start_sandbox`) returns `{ application_id, auth_token, expires_at, user_id }`: a 30-minute session of a Cnamio test application. Use it as `Authorization: Bearer ` with header `applicationId: ` on `/checkdomain`, `/connect`, `/connect/automatic` and `/connect/{jobId}/status` (MCP: pass it as `sandboxToken`). Any domain connects at once; `conflict.` has a record in the way; `pending.` never propagates; provider token `invalid` is refused. Nothing real is read or written. Use it to check your headless code and your understanding of the answers; it has no webhook and no secret. 2. **Free account for the developer.** Ask for their email and whether they agree to the Terms (https://cnamio.com/terms) and the Privacy Policy (https://cnamio.com/privacy). Only then (or, if they prefer, they sign up themselves at https://cnamio.com/?utm_source=skill&utm_medium=agent#start): ```bash curl -s https://api.cnamio.com/v1/agent/signup -H 'Content-Type: application/json' \ -d '{"email":"dev@example.com","consent":true,"name":"Ana","client":{"name":"your-agent-name"}}' # → 202 { "received": true, "next_steps": [...], "sandbox": { ...a sandbox session... } } ``` (MCP: `start_signup`.) Cnamio emails them a link, saying an agent asked for it; opening it shows the Terms and the Privacy Policy, and once the developer accepts them there it creates the account: a test application (sandbox provider) and a live application on the free plan. Nothing is created before that, and the answer is the same whether or not the address already has an account (an existing one receives a sign-in link). 3. **The developer finishes it.** They open the link, generate the test application's secret in the dashboard (https://api.cnamio.com/panel) and set `CNAMIO_APPLICATION_ID` and `CNAMIO_SECRET` in the server environment themselves. Never ask them to paste the secret into the chat. Meanwhile, keep building with the sandbox session; switch to the test application's credentials, then to the live application's, when they are in the environment. Sign-ups and sandbox sessions are limited per address and per email, and each sandbox session to 20 distinct domains and 30 requests a minute (a 429 means wait, or get a new session); calls from a browser (with an `Origin` header) are refused. ## What to do, in order Follow these steps in the project you are working on. Adapt names and file locations to the project's framework and conventions; the examples use Node.js (Express or Next.js route handlers) and Python (FastAPI). **Shortcut for Node.js and Python projects:** instead of writing the HTTP calls by hand, install the server SDK (`npm i cnamio` or `pip install cnamio`; or save the single file into the project, for example `lib/cnamio.mjs` plus `lib/cnamio.d.mts`, or `app/cnamio.py`). It has no dependencies and sends its own User-Agent. It maps onto the steps below: ```js import { Cnamio, recordsForUser, verifyWebhook } from 'cnamio'; const cnamio = new Cnamio(); // reads CNAMIO_APPLICATION_ID and CNAMIO_SECRET const records = recordsForUser({ target: 'customers.yourapp.com', userId, ownershipKey: process.env.CNAMIO_OWNERSHIP_KEY }); // step 1 const session = await cnamio.createSession({ userId, dnsRecords: records }); // step 3: send to the page as is const check = await cnamio.checkDomain(domain, records); // step 4b const job = await cnamio.connect(domain, records, { userId }); // step 4b (or connectAutomatic(domain, records, providerToken)) verifyWebhook(rawBody, req.headers, process.env.CNAMIO_WEBHOOK_SECRET); // step 5 ``` Python has the same functions in snake_case (`Cnamio()`, `records_for_user(...)`, `create_session(...)`, `check_domain(...)`, `connect(...)`, `verify_webhook(raw, request.headers, secret)`). Errors raise `CnamioError` with `status` (and `conflicts`, a list of reason codes, on the 409 of `connect_automatic`). A `503` means "not now": wait the seconds in `Retry-After` and repeat the same call. The client keeps its own server-side session and renews it. ### 1. Decide the DNS records Find out what a custom domain must point to in this product. Usually it is one CNAME from the user's domain to a hostname of the app's hosting (for example a "custom hostname" target). If the project does not say, ask the owner. **Add an ownership record per user.** When every user of the app points their domain at the same CNAME target, the CNAME alone does not prove who owns the domain: if user A already pointed `links.mybrand.com` at you, user B could start a connection for the same name, it would verify at once, and the webhook would credit user B. Require a TXT record whose value is unique to the user, so only the person who controls the domain's DNS can complete the connection. Build the records on the server, per user: ```js import { createHmac } from 'node:crypto'; // Value unique to this user and stable across retries. CNAMIO_OWNERSHIP_KEY is any long random server secret of yours. const ownershipValue = userId => 'yourapp-verify=' + createHmac('sha256', process.env.CNAMIO_OWNERSHIP_KEY).update(String(userId)).digest('hex').slice(0, 32); function dnsRecordsFor(userId) { return [ { type: 'CNAME', host: '{SUBDOMAIN}', value: 'customers.yourapp.com', ttl: 300 }, { type: 'TXT', host: '_yourapp-verify.{SUBDOMAIN}', value: ownershipValue(userId), ttl: 300 }, ]; } ``` Use these same records for the session (step 3), the window (step 4a) and the headless flow (step 4b); `domain.added` then means the CNAME and this user's TXT are both live. Skip the TXT only if your hosting already verifies ownership per customer some other way. Placeholders: `{DOMAIN}` (the zone, for example `meustudio.com.br`), `{SUBDOMAIN}` (everything left of the zone), `{SLD}` and `{TLD}` (`meustudio` and `com.br`); `@` is the zone apex. Unknown `{…}` tokens are refused, so per-user values are built in your code as above. The zone is the domain's real DNS zone found from its nameservers, so public suffixes like `com.br` and multi-level names work: `agenda.meustudio.com.br` in zone `meustudio.com.br` gives `{SUBDOMAIN}` = `agenda`; `a.b.x.com.br` in zone `x.com.br` gives `a.b`. Types: A, AAAA, CNAME, TXT, MX, CAA. Up to 20 records. Apex domains (`mybrand.com` itself): DNS does not allow a CNAME there, and Cnamio refuses one with `400` (the connect window sends the user back to the domain field with an "invalid domain" message). If your hosting gives fixed IP addresses, send `A`/`AAAA` records with host `@` for apex domains; otherwise tell users to connect a subdomain such as `links.mybrand.com`, and say so in your UI before they type. Cnamio only handles DNS. If your hosting also has to know each new hostname (a "custom hostname" or certificate API), call it in your own code: before opening the window, or when the `domain.added` webhook arrives. ### 2. Add the credentials to the server environment ```bash CNAMIO_APPLICATION_ID=app_… # not secret, may also be exposed to the browser CNAMIO_SECRET=cnm_sk_… # server only: never in client code, never committed CNAMIO_WEBHOOK_SECRET=… # from GET /v1/manage/webhook-secret or the dashboard CNAMIO_OWNERSHIP_KEY=… # your own random secret for the per-user TXT value (step 1) ``` Add the names (without values) to `.env.example` or the project's equivalent. Do not commit real values. ### 3. Server route that creates a session token The browser never sees the secret. Your server, after authenticating your user, asks Cnamio for a 60-minute session token. Node.js (Express): ```js app.post('/api/cnamio/session', requireUser, async (req, res) => { const dnsRecords = dnsRecordsFor(req.user.id); // step 1, built on the server const r = await fetch('https://api.cnamio.com/token', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ applicationId: process.env.CNAMIO_APPLICATION_ID, secret: process.env.CNAMIO_SECRET, userId: String(req.user.id), // echoed in jobs and webhooks dnsRecords, // binds the session to these records }), }); if (!r.ok) return res.status(502).json({ error: 'cnamio_unavailable' }); const { auth_token } = await r.json(); res.json({ token: auth_token, applicationId: process.env.CNAMIO_APPLICATION_ID, dnsRecords }); }); ``` Next.js (App Router, `app/api/cnamio/session/route.ts`): ```ts export async function POST() { const user = await getCurrentUser(); // the project's own auth if (!user) return new Response('Unauthorized', { status: 401 }); const dnsRecords = dnsRecordsFor(user.id); // step 1 const r = await fetch('https://api.cnamio.com/token', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ applicationId: process.env.CNAMIO_APPLICATION_ID, secret: process.env.CNAMIO_SECRET, userId: String(user.id), dnsRecords }), cache: 'no-store', }); if (!r.ok) return Response.json({ error: 'cnamio_unavailable' }, { status: 502 }); const { auth_token } = await r.json(); return Response.json({ token: auth_token, applicationId: process.env.CNAMIO_APPLICATION_ID, dnsRecords }); } ``` Python (FastAPI; `pip install httpx`, FastAPI does not bring it): ```python import hashlib, hmac, os import httpx from fastapi import Depends, HTTPException def dns_records_for(user_id) -> list[dict]: # step 1 in Python key = os.environ["CNAMIO_OWNERSHIP_KEY"].encode() value = "yourapp-verify=" + hmac.new(key, str(user_id).encode(), hashlib.sha256).hexdigest()[:32] return [ {"type": "CNAME", "host": "{SUBDOMAIN}", "value": "customers.yourapp.com", "ttl": 300}, {"type": "TXT", "host": "_yourapp-verify.{SUBDOMAIN}", "value": value, "ttl": 300}, ] @app.post("/api/cnamio/session") async def cnamio_session(user=Depends(current_user)): app_id, secret = os.environ.get("CNAMIO_APPLICATION_ID"), os.environ.get("CNAMIO_SECRET") if not app_id or not secret: raise HTTPException(503, "custom_domains_not_configured") records = dns_records_for(user.id) # step 1, built on the server async with httpx.AsyncClient(timeout=20) as client: r = await client.post("https://api.cnamio.com/token", json={ "applicationId": app_id, "secret": secret, "userId": str(user.id), "dnsRecords": records, }) if r.status_code != 200: raise HTTPException(502, "cnamio_unavailable") return {"token": r.json()["auth_token"], "applicationId": app_id, "dnsRecords": records} ``` Optional body fields `domain` and `dnsRecords` bind the session to exactly those values (each can be bound on its own). Binding `dnsRecords` stops a browser from changing the target or the ownership value; the window must then send the identical array (compared exactly, `ttl` included), so return it from the route along with the token, as above. `userId` is optional (any string up to 128 characters); without it, `user_id` is `null` in jobs and webhooks, so send it. Call the route with whatever credentials your app's auth uses (cookies are sent automatically on same-origin `fetch`; add your auth header otherwise). A session lasts 60 minutes: reuse it instead of creating one per click, since `/token` calls from your server share one address and count against the same limit. ### 4a. Browser: open the connect window (recommended for user-facing apps) Load the SDK once and open the window from the place where users manage their domain: ```html ``` ```js async function connectCustomDomain(prefilledDomain) { const r = await fetch('/api/cnamio/session', { method: 'POST' }); if (!r.ok) throw new Error('Custom domains are unavailable right now.'); // show it in your UI const { token, applicationId, dnsRecords } = await r.json(); window.cnamio.connectDomain({ applicationId, token, applicationName: 'Your App', // shown in the window locale: 'en', // 'en', 'pt-BR' or 'es' dnsRecords, // exactly the array the session was bound to ...(prefilledDomain ? { prefilledDomain } : {}), }); } window.addEventListener('onCnamioSuccess', e => { // e.detail: { domain, success: true, setupType: 'automatic' | 'manual', provider, jobId } // Automatic: the records were written. Manual: the user says they added the records. // Either way propagation is not confirmed yet: store the domain as "pending" with e.detail.jobId. // Only the domain.added webhook (step 5) means "connected". }); window.addEventListener('onCnamioClose', e => { /* e.detail.lastStatus */ }); ``` The window runs in an iframe from Cnamio's origin; the token reaches it only through `postMessage`. Options: `forceManualSetup: true` (with `prefilledDomain`) always shows the copy-the-records steps; `primaryColor: '#…'` matches your brand. For single-page apps, also add the script to the page template (not a dynamic import from another host). ### 4b. Headless API flow (agents, CLIs, backends without a UI) Use the session token on the REST routes, from your server or an agent: ```bash TOKEN=$(curl -s https://api.cnamio.com/token -H 'Content-Type: application/json' \ -d "{\"applicationId\":\"$CNAMIO_APPLICATION_ID\",\"secret\":\"$CNAMIO_SECRET\"}" | jq -r .auth_token) H=(-H "Authorization: Bearer $TOKEN" -H "applicationId: $CNAMIO_APPLICATION_ID" -H 'Content-Type: application/json') # The same per-user records as step 1 (here with a fixed example ownership value): RECORDS='[{"type":"CNAME","host":"{SUBDOMAIN}","value":"customers.yourapp.com","ttl":300},{"type":"TXT","host":"_yourapp-verify.{SUBDOMAIN}","value":"yourapp-verify=","ttl":300}]' # 1) Where is the DNS? Can it be automatic? → provider, setupType, connectMethods, recordState curl -s https://api.cnamio.com/checkdomain "${H[@]}" -d "{\"domain\":\"shop.customer.com\",\"dnsRecords\":$RECORDS,\"checkConflicts\":true}" # 2a) The user has an API token for that provider (connectMethods contains "api_token"): curl -s https://api.cnamio.com/connect/automatic "${H[@]}" -d "{\"domain\":\"shop.customer.com\",\"dnsRecords\":$RECORDS,\"providerToken\":\"\"}" # 2b) Otherwise: get the exact records to show the user and start watching propagation: curl -s https://api.cnamio.com/connect "${H[@]}" -d "{\"domain\":\"shop.customer.com\",\"dnsRecords\":$RECORDS}" # 3) Follow it (or wait for the webhook): curl -s https://api.cnamio.com/connect/JOB_ID/status "${H[@]}" ``` Statuses: `pending` → `completed` (connected) or `failed` (72 hours without propagation). `409` means existing records block the connection and nothing was changed: show `conflicts` to the user. `422` means the provider refused the token or automatic setup is not available: fall back to step 2b. A provider token is used once and must not be stored or logged by your code either. ### 5. Webhook endpoint (source of truth) Cnamio POSTs `domain.added` when every required record is live and `domain.propagation.timeout` after 72 hours without it. Verify the signature over the **raw** body before parsing: ```js import { createHmac, timingSafeEqual } from 'node:crypto'; export 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); // compare byte lengths, then bytes } // Express: the raw body is needed for this route only. Register it BEFORE any global // app.use(express.json()), or the JSON parser consumes the body and every signature fails. app.post('/webhooks/cnamio', express.raw({ type: 'application/json' }), (req, res) => { const raw = req.body.toString('utf8'); if (!verifyCnamio(raw, req.headers, process.env.CNAMIO_WEBHOOK_SECRET)) return res.sendStatus(401); const event = JSON.parse(raw); // Idempotent: the same event.id may arrive again (retries after 1, 5 and 30 minutes). 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); }); ``` In Next.js, read `await request.text()` for the raw body. In Python (FastAPI), read the raw body and use the timestamp header exactly as received: ```python import hashlib, hmac, json, os, time from fastapi import Request, Response def verify_cnamio(raw: bytes, headers, secret: str | None) -> bool: ts = headers.get("cnamio-timestamp", "") given = headers.get("cnamio-signature", "") if not secret or not ts.isdigit() or abs(time.time() - int(ts)) > 300: return False expected = "sha256=" + hmac.new(secret.encode(), ts.encode() + b"." + raw, hashlib.sha256).hexdigest() return hmac.compare_digest(expected.encode(), given.encode()) @app.post("/webhooks/cnamio") async def cnamio_webhook(request: Request): raw = await request.body() secret = os.environ.get("CNAMIO_WEBHOOK_SECRET") if not secret: return Response(status_code=503) # misconfigured: Cnamio retries later if not verify_cnamio(raw, request.headers, secret): return Response(status_code=401) event = json.loads(raw) # Idempotent by event["id"]; then mark event["user_id"] / event["domain"] connected or failed. return Response(status_code=200) ``` Answer `2xx` only after you stored the result. Non-`2xx` answers are retried after 1, 5 and 30 minutes; after the fourth attempt Cnamio stops, and the status stays readable with `GET /connect/{jobId}/status` (or `GET /v1/manage/jobs?domain=`), so a periodic reconciliation of pending domains closes any gap. After a domain is connected Cnamio keeps monitoring it (read-only DNS checks, included). When its records disappear your webhook receives `domain.records_missing` (`health` is `degraded` or `broken`, `data.records_missing` lists what is gone) and, when they are back, `domain.records_restored`. Handle them if the product should warn the user or stop serving the domain; otherwise ignore them, as any event type you do not handle. The same state is in `health` of `GET /connect/{jobId}/status`. Payload of `domain.added` / `domain.propagation.timeout` (full schema: `WebhookEvent` in https://cnamio.com/openapi.json): ```json { "id": "6f1c…", "type": "domain.added", "job_id": "job_…", "user_id": "u1", "domain": "links.mybrand.com", "subdomain": "links", "provider": "cloudflare", "setup_type": "automatic", "propagation_status": "success", "optional_records_propagation_status": "exempt", "cname_target": "custom.yourapp.com", "data": { "records_propagated": [{ "type": "CNAME", "host": "links.mybrand.com", "value": "custom.yourapp.com" }], "records_non_propagated": [] } } ``` `webhook.test` carries only `{ id, type: "webhook.test", application_id, created_at }`: answer 200. Events for users or domains you do not know should also get a 200 (and be logged), so they are not retried. Register the URL (public HTTPS; private and internal addresses are refused; redirects are not followed): ```bash 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"}' curl -s -u "$CNAMIO_APPLICATION_ID:$CNAMIO_SECRET" https://api.cnamio.com/v1/manage/webhook-secret # → CNAMIO_WEBHOOK_SECRET curl -s -X POST -u "$CNAMIO_APPLICATION_ID:$CNAMIO_SECRET" https://api.cnamio.com/v1/manage/webhook-test # signed webhook.test ``` ### 6. Verify the integration 1. `POST /api/cnamio/session` as a signed-in user returns a token (and the secret is absent from every client bundle: search the build output for `cnm_sk_`). 2. `POST /v1/manage/webhook-test` returns `{ "delivered": true }` and your endpoint accepted the signature. 3. `POST /checkdomain` for a real domain returns the provider and `recordState`. 4. Optional end-to-end: connect a test subdomain you own, wait for `domain.added`, then remove the record. ## Use Cnamio from an MCP client Agents can also use Cnamio directly as tools through the MCP server at `https://api.cnamio.com/mcp` (Streamable HTTP). Without credentials: `get_integration_guide`, `start_sandbox` (a sandbox session to pass as `sandboxToken` to the domain tools) and `start_signup` (step 0). With 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). Add the server with no credentials to start (`claude mcp add --transport http cnamio https://api.cnamio.com/mcp`). MCP clients that support OAuth (claude.ai and ChatGPT connectors, Claude Code, Cursor) need no header at all: the first domain tool answers 401 with the resource metadata, and the person signs in to Cnamio and approves one application. Otherwise, once the developer has them, 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. ## Rules - The secret stays on the server. The browser and agents running on behalf of end users get session tokens only. - Never store, log or forward a DNS provider token. Pass it straight to `/connect/automatic`. - Treat the webhook as the source of truth; the browser event can be lost if the user closes the tab, and in manual setups it only means the user says the records were added. - Limits: By default 60 requests per minute per address and per session token, under a ceiling of 600 per application. Your server is one address for all of your users, so reuse session tokens and ask for a per-application limit for server-to-server traffic. Errors are `{ "message": "…" }` with a fixed text. - Content-Security-Policy: allow `script-src https://connect.cnamio.com` and `frame-src https://connect.cnamio.com` on the page that opens the window (and `connect-src https://connect.cnamio.com` if you call `cnamio.checkDomain` from the browser). The SDK at `/sdk/v1.js` is updated in place for fixes, so do not pin it with Subresource Integrity. - Retrying and changing domains: Cnamio never deletes records. After `failed`, or to switch to another domain, create a new session and connect again (a new `job_id`). To disconnect, stop serving the domain in your app and tell the user they may remove the records. - Setting or changing the webhook URL (`PUT /v1/manage/webhook`) does not change the webhook secret. - Do not promise one-click connection to your users: today automatic setup uses a provider API token, and the manual steps are always available. ## Reference | Route | Auth | Purpose | | --- | --- | --- | | `POST /v1/agent/sandbox` | none (no `Origin`) | a 30-minute sandbox session for agents | | `POST /v1/agent/signup` | none (no `Origin`) | `{ email, consent: true, name?, company?, locale?, client? }`: emails the developer the link that creates their free account | | `POST /token` | body: applicationId + secret | session token (60 min) | | `POST /checkdomain` | Bearer + `applicationId` header | provider, setup type, connect methods, record state, conflicts | | `POST /connect` | Bearer | manual: exact records, starts watching | | `POST /connect/automatic` | Bearer | creates records with the user's provider token | | `GET /connect/{jobId}/status` | Bearer | `pending` / `completed` / `failed`, and `health` (`healthy` / `degraded` / `broken`) once connected | | `POST /connect/propagation/recheck/{jobId}` | Bearer | check now (once per 5 min; `409` when the connection is already finished) | | `GET /connect/webhooks/last/{jobId}` | Bearer | last webhook and delivery state | | `GET /v1/manage/jobs?domain=&health=&share_link_id=` | Basic | list connections (with monitoring state) | | `POST /v1/manage/share-links` | Basic | `{ domains, dnsRecords, maxUses?, expiresInDays?, userId? }`: a link (`url`, shown once) for whoever manages the DNS (agency, IT team); `POST …/{id}/revoke` ends it | | `PUT /v1/manage/monitoring` | Basic | `{ enabled }`: continuous monitoring on or off | | `PUT /v1/manage/webhook` · `GET …/webhook-secret` · `POST …/webhook-test` | Basic | webhook setup | | `GET /v1/manage/usage?month=YYYY-MM` | Basic | usage (each connected domain counts once per month) | Questions: contato@cnamio.com · Paste-ready block for a project's AGENTS.md: https://cnamio.com/agent-onboarding/AGENTS.md # Custom domains your coding agent can add. Cnamio is documented for machines as carefully as for people: a skill an agent can follow, an MCP server it can call, an OpenAPI document and plain-text docs. Paste one line and review what it wrote. ## Start with one line Paste this into your AI coding agent, in the project where users should be able to connect a domain: **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. ``` The agent needs your application id and secret in the environment. If you do not have them yet, it can start without them (below), or you can [create a free account](https://cnamio.com/#start) yourself. The skill tells the agent never to invent or hard-code credentials, and never to ask you to paste the secret into the chat. ## No account yet: sandbox now, sign-up by email An agent can take you from zero to a working integration in one session, without you leaving the editor until the last step: 1. **Sandbox at once.** `POST https://api.cnamio.com/v1/agent/sandbox` (MCP: `start_sandbox`) returns a 30-minute session of a Cnamio test application, with no account and no credentials. The agent runs the check, the connection and the status calls end to end against the sandbox provider: any domain connects, `conflict.` and `pending.` prefixes simulate a record in the way and one that never appears. Nothing real is read or written. 2. **Your free account.** With your email and your agreement to the [Terms](https://cnamio.com/terms) and the [Privacy Policy](https://cnamio.com/privacy), the agent calls `POST https://api.cnamio.com/v1/agent/signup` (MCP: `start_signup`). You receive a link; opening it creates the account, with a test application and a live one on the free plan. Nothing is created before you open it. 3. **You finish it.** In the [dashboard](https://api.cnamio.com/panel) you generate the secret and put `CNAMIO_APPLICATION_ID` and `CNAMIO_SECRET` in your server's environment. The agent switches from the sandbox to your test application, then to the live one. ``` curl -s -X POST https://api.cnamio.com/v1/agent/sandbox curl -s https://api.cnamio.com/v1/agent/signup -H 'Content-Type: application/json' \ -d '{"email":"YOUR_EMAIL","consent":true}' ``` Both routes are for agents and their tools: a request from a browser (with an `Origin` header) is refused, and sign-ups and sandbox sessions are limited per address and per email. ## What the skill makes the agent do 1. Decide the DNS records your hosting needs, with an ownership TXT per user. 2. Add the environment variable names to the project, without values. 3. Write the server route that creates a session token, behind your own authentication. 4. Open the connect window from your domain settings page, or use the headless API when there is no user interface. 5. Write the webhook endpoint, verifying the signature over the raw body. 6. Check the integration: a session, a signed test webhook, a real domain lookup. It carries complete examples for Express, Next.js route handlers and FastAPI, and tells the agent to follow your framework's conventions instead of copying them blindly. Read it yourself at [`/agent-onboarding/SKILL.md`](https://cnamio.com/agent-onboarding/SKILL.md). ## Files for agents Plain files, no HTML to scrape, readable from any origin: | File | What it is | | --- | --- | | [`/agent-onboarding/SKILL.md`](https://cnamio.com/agent-onboarding/SKILL.md) | The integration skill: step by step, with Node.js and Python examples. | | [`/llms.txt`](https://cnamio.com/llms.txt) | A short index of everything below, for language models and search agents. | | [`/llms-full.txt`](https://cnamio.com/llms-full.txt) | Everything below in one file: docs, quickstart, skill, recipes, providers and security. | | [`/docs.md`](https://cnamio.com/docs.md) | The developer docs in Markdown. Every reading page also has its `.md`: [quickstart](https://cnamio.com/quickstart.md), [agents](https://cnamio.com/agents.md), [providers](https://cnamio.com/providers.md), [security](https://cnamio.com/security.md). | | [`/recipes/*.md`](https://cnamio.com/recipes/nextjs.md) | Framework recipes: Next.js, Express, Rails, Laravel, Django. | | [`/agent-onboarding/AGENTS.md`](https://cnamio.com/agent-onboarding/AGENTS.md) | A block to paste into your project's AGENTS.md. | | [`/openapi.json`](https://cnamio.com/openapi.json) | OpenAPI 3.1: every route, request and response, and the webhook payload. | | [`/sdk/cnamio.mjs`](https://cnamio.com/sdk/cnamio.mjs) | Server SDK for Node.js 18+, one file, with types in [`cnamio.d.mts`](https://cnamio.com/sdk/cnamio.d.mts). | | [`/sdk/cnamio.py`](https://cnamio.com/sdk/cnamio.py) | Server SDK for Python 3.9+, standard library only. | ## MCP server Agents can use Cnamio directly as tools at `https://api.cnamio.com/mcp` (Streamable HTTP). It is listed in the official MCP Registry as `com.cnamio/domains`. The tools behave exactly like the REST routes: same validation, same limits. | Tool | What it does | | --- | --- | | `get_integration_guide` | Returns the integration guide. Needs no credentials. | | `start_sandbox` | A 30-minute sandbox session, no credentials. The domain tools below take it as `sandboxToken`. | | `start_signup` | Emails the developer the link that creates their free account. Needs their email and their consent. | | `check_domain` | Read-only: DNS provider, setup type, connect methods, nameservers and conflicts with existing records. | | `connect_domain` | Returns the exact records to create and starts watching propagation. | | `connect_domain_automatic` | Creates the records with the user's provider token, used once. | | `get_connection_status` | Whether a connection is pending, completed or failed. | | `recheck_propagation` | Checks again now, at most once every 5 minutes. A finished connection answers 409. | | `list_connections` | Recent connections of the application. | | `create_share_link` | A link for whoever manages the DNS (an agency, the IT team): they connect the domains without your keys. | | `revoke_share_link` | Ends a shareable link at once. | Add it with no credentials to start: `claude mcp add --transport http cnamio https://api.cnamio.com/mcp`. Three ways to authenticate the domain tools: [OAuth](https://cnamio.com/agents#connectors) (connectors in claude.ai and ChatGPT, and any MCP client that signs in by itself), the application credentials as HTTP Basic, or a session token as `Bearer` plus an `applicationId` header. With Basic, in 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')" ``` In clients configured with JSON: ``` { "mcpServers": { "cnamio": { "url": "https://api.cnamio.com/mcp", "headers": { "Authorization": "Basic " } } } } ``` **Keep this configuration out of version control.** It carries the application secret. ## Connect in claude.ai or ChatGPT No secret to paste: the connector signs you in to Cnamio with OAuth 2.1, and you choose which of your applications the assistant may act for. 1. **Claude** (claude.ai, Desktop, mobile): in Settings, Connectors, add a custom connector with the URL `https://api.cnamio.com/mcp`. **ChatGPT**: in Settings, Apps, create an app (developer mode) with the same URL and OAuth authentication. Other MCP clients that support OAuth (Claude Code, Cursor, VS Code) take the same URL with no header. 2. The integration guide works at once. The first time the assistant checks or connects a domain, it asks you to connect: you land on a Cnamio page. 3. Sign in with your account email (we send a link; open it in the same browser), pick the application and look at the permissions, then choose **Authorize**. You go back to the assistant, which carries on. | Permission | What it allows | Tools | | --- | --- | --- | | `domains:read` | See where a domain's DNS is hosted and follow the application's connections. | `check_domain`, `get_connection_status`, `list_connections` | | `domains:write` | Start connections: manual records, or with the provider token the domain owner gives. Existing records are never deleted. | `connect_domain`, `connect_domain_automatic`, `recheck_propagation` | | `share_links:write` | Create and revoke connection links for whoever manages the DNS. | `create_share_link`, `revoke_share_link` | Access tokens last one hour and are renewed by the connector; renewing rotates the refresh token, and a refresh token used twice ends the connection. Pick your **test** application to try it: everything runs in the sandbox and no real DNS is read or changed. To cut access, open the dashboard, **Connected agents**, and revoke it. Discovery for client developers: [`/.well-known/oauth-protected-resource/mcp`](https://api.cnamio.com/.well-known/oauth-protected-resource/mcp) and [`/.well-known/oauth-authorization-server`](https://api.cnamio.com/.well-known/oauth-authorization-server) (PKCE S256, Client ID Metadata Documents and dynamic registration). ### Em português: conectar no claude.ai ou no ChatGPT Nenhum segredo para colar: o conector faz você entrar no Cnamio por OAuth 2.1, e você escolhe por qual das suas aplicações o assistente pode agir. 1. **Claude** (claude.ai, Desktop, celular): em Configurações, Conectores, adicione um conector personalizado com a URL `https://api.cnamio.com/mcp`. **ChatGPT**: em Configurações, Apps, crie um app (modo de desenvolvedor) com a mesma URL e autenticação OAuth. Outros clientes MCP com OAuth (Claude Code, Cursor, VS Code) usam a mesma URL, sem cabeçalho. 2. O guia de integração funciona na hora. Na primeira vez que o assistente consultar ou conectar um domínio, ele pede para você se conectar e abre uma página do Cnamio. 3. Entre com o e-mail da sua conta (enviamos um link; abra no mesmo navegador), escolha a aplicação, confira as permissões e clique em **Autorizar**. Você volta ao assistente, que continua de onde parou. Permissões: `domains:read` (ver onde o DNS está e acompanhar as conexões), `domains:write` (iniciar conexões; registros existentes nunca são apagados) e `share_links:write` (links de conexão para quem cuida do DNS). Para testar, escolha a aplicação de **teste**: tudo roda no sandbox. Para cortar o acesso, abra o painel, **Agentes conectados**, e revogue. ### En español: conectar en claude.ai o ChatGPT Ningún secreto que pegar: el conector te hace entrar a Cnamio con OAuth 2.1, y tú eliges por cuál de tus aplicaciones puede actuar el asistente. 1. **Claude** (claude.ai, Desktop, móvil): en Configuración, Conectores, agrega un conector personalizado con la URL `https://api.cnamio.com/mcp`. **ChatGPT**: en Configuración, Apps, crea una app (modo desarrollador) con la misma URL y autenticación OAuth. Otros clientes MCP con OAuth (Claude Code, Cursor, VS Code) usan la misma URL, sin encabezado. 2. La guía de integración funciona al instante. La primera vez que el asistente consulte o conecte un dominio, te pide conectarte y abre una página de Cnamio. 3. Entra con el correo de tu cuenta (enviamos un enlace; ábrelo en el mismo navegador), elige la aplicación, revisa los permisos y haz clic en **Autorizar**. Vuelves al asistente, que sigue donde estaba. Permisos: `domains:read` (ver dónde está el DNS y seguir las conexiones), `domains:write` (iniciar conexiones; los registros existentes nunca se borran) y `share_links:write` (enlaces de conexión para quien maneja el DNS). Para probar, elige la aplicación de **prueba**: todo corre en el sandbox. Para cortar el acceso, abre el panel, **Agentes conectados**, y revócalo. ## Headless flow For agents, CLIs and backends without a user interface, the same connection runs over the API. With the Node.js SDK (Python has the same functions in snake_case): ``` import { Cnamio, recordsForUser } from './lib/cnamio.mjs'; const cnamio = new Cnamio(); const records = recordsForUser({ target: 'customers.yourapp.com', userId, ownershipKey: process.env.CNAMIO_OWNERSHIP_KEY }); // 1. Where is the DNS, and can the records be created with a token? const check = await cnamio.checkDomain('shop.customer.com', records); // 2. Create them with the user's provider token, or get the exact records to show. const job = providerToken && check.connectMethods.includes('api_token') ? await cnamio.connectAutomatic('shop.customer.com', records, providerToken, { userId }) : await cnamio.connect('shop.customer.com', records, { userId }); // 3. Follow it, or wait for the domain.added webhook. const { connected, status } = await cnamio.status(job.job_id); ``` A `409` means existing records block the connection and nothing was changed: show the conflicts to the user. A `422` means the provider refused the token: fall back to `connect`. Which providers accept a token is on the [providers page](https://cnamio.com/providers). ## A block for your AGENTS.md So that every agent working in your repository knows how custom domains work there, paste [`/agent-onboarding/AGENTS.md`](https://cnamio.com/agent-onboarding/AGENTS.md) into your `AGENTS.md`, `CLAUDE.md` or editor rules: ``` curl -s https://cnamio.com/agent-onboarding/AGENTS.md >> AGENTS.md ``` Framework recipes with real code: [Next.js](https://cnamio.com/recipes/nextjs.md), [Express](https://cnamio.com/recipes/express.md), [Rails](https://cnamio.com/recipes/rails.md), [Laravel](https://cnamio.com/recipes/laravel.md) and [Django](https://cnamio.com/recipes/django.md). ## Rules we give every agent - The secret stays on the server. Browsers, and agents acting for end users, get 60-minute session tokens only. - Never store, log or forward a DNS provider token: pass it straight to the automatic connection. - Treat the webhook as the source of truth. A browser event can be lost when the user closes the tab. - Cnamio never deletes DNS records. To retry or change domains, start a new connection. --- This is the Markdown of https://cnamio.com/agents. Every page for agents: https://cnamio.com/llms.txt # Recipe: custom domains in a Next.js app (App Router) Let the users of a Next.js app connect their own domain with Cnamio: a session route on the server, the connect window in a client component, and a webhook route that marks the domain live. Uses the Node.js server SDK (`npm i cnamio`, Node.js 18+, no dependencies). The full guide is https://cnamio.com/agent-onboarding/SKILL.md. ## 1. Install and configure ```bash npm i cnamio ``` Or vendor the single file instead: `curl -s https://cnamio.com/sdk/cnamio.mjs -o lib/cnamio-sdk.mjs` (types: `cnamio.d.mts`) and import from it. ```bash # .env.local (values never committed; add the names without values to .env.example) CNAMIO_APPLICATION_ID=app_… CNAMIO_SECRET=cnm_sk_… CNAMIO_OWNERSHIP_KEY=… # any long random secret of yours CNAMIO_WEBHOOK_SECRET=… # from the dashboard or GET /v1/manage/webhook-secret ``` No account yet? A coding agent can call the MCP tool `start_signup` (or `POST https://api.cnamio.com/v1/agent/signup`) with your email, and work in the sandbox until you open the verification link. ## 2. One client for the server: `lib/cnamio.ts` ```ts import 'server-only'; import { Cnamio, recordsForUser } from 'cnamio'; export const cnamio = new Cnamio(); // reads CNAMIO_APPLICATION_ID and CNAMIO_SECRET /** A CNAME to your hosting plus a TXT only this user can satisfy. */ export function recordsFor(userId: string) { return recordsForUser({ target: 'customers.yourapp.com', userId, ownershipKey: process.env.CNAMIO_OWNERSHIP_KEY! }); } ``` Replace `customers.yourapp.com` with the hostname your hosting gives for custom domains. ## 3. Session route: `app/api/cnamio/session/route.ts` ```ts import { cnamio, recordsFor } from '@/lib/cnamio'; import { getCurrentUser } from '@/lib/auth'; // your own auth export async function POST() { const user = await getCurrentUser(); if (!user) return new Response('Unauthorized', { status: 401 }); try { // { token, applicationId, dnsRecords, expiresAt }: hand it to the browser as is. return Response.json(await cnamio.createSession({ userId: user.id, dnsRecords: recordsFor(user.id) })); } catch { return Response.json({ error: 'cnamio_unavailable' }, { status: 502 }); } } ``` ## 4. Connect button: `app/settings/domain/connect-domain.tsx` ```tsx 'use client'; import Script from 'next/script'; declare global { interface Window { cnamio?: { connectDomain(config: Record): void } } } export function ConnectDomain() { async function open() { const r = await fetch('/api/cnamio/session', { method: 'POST' }); if (!r.ok) return alert('Custom domains are unavailable right now.'); const session = await r.json(); window.cnamio?.connectDomain({ ...session, applicationName: 'Your App', locale: 'en' }); } return ( <> ``` ## 4. Headless (no UI: CLIs, agents, admin jobs) ```js const records = recordsFor(user.id); const check = await cnamio.checkDomain('shop.customer.com', records); // provider, setupType, connectMethods, conflicts const job = check.connectMethods.includes('api_token') && providerToken ? await cnamio.connectAutomatic('shop.customer.com', records, providerToken, { userId: user.id }) : await cnamio.connect('shop.customer.com', records, { userId: user.id }); // exact records to show the user console.log((await cnamio.status(job.job_id)).status); ``` ## 5. Check it With the test application's credentials every domain goes to the sandbox provider: `shop.example.com` connects at once, `conflict.example.com` shows a conflict, `pending.example.com` never propagates. Then `await cnamio.manage.setWebhookUrl('https://yourapp.com/webhooks/cnamio')` and `await cnamio.manage.testWebhook()`. # Recipe: custom domains in a Ruby on Rails app Let the users of a Rails app connect their own domain with Cnamio: a session endpoint, the connect window in a view, and a webhook endpoint. There is no Ruby SDK: this recipe calls the REST API with the standard library (`net/http`, `openssl`), exactly what the Node.js and Python SDKs do. The full guide is https://cnamio.com/agent-onboarding/SKILL.md; every route is in https://cnamio.com/openapi.json. ## 1. Configure ```bash CNAMIO_APPLICATION_ID=app_… CNAMIO_SECRET=cnm_sk_… # server only, never committed CNAMIO_OWNERSHIP_KEY=… # any long random secret of yours CNAMIO_WEBHOOK_SECRET=… ``` No account yet? A coding agent can call the MCP tool `start_signup` (or `POST https://api.cnamio.com/v1/agent/signup`) with your email, and work in the sandbox until you open the verification link. ## 2. A small client: `app/services/cnamio.rb` ```ruby require "json" require "net/http" require "openssl" module Cnamio API = URI("https://api.cnamio.com") # A CNAME to your hosting plus a TXT only this user can satisfy (same values as recordsForUser in the SDKs). def self.records_for(user_id, target: "customers.yourapp.com", prefix: "cnamio-verify") value = OpenSSL::HMAC.hexdigest("SHA256", ENV.fetch("CNAMIO_OWNERSHIP_KEY"), user_id.to_s)[0, 32] [ { type: "CNAME", host: "{SUBDOMAIN}", value: target, ttl: 300 }, { type: "TXT", host: "_#{prefix}.{SUBDOMAIN}", value: "#{prefix}=#{value}", ttl: 300 }, ] end # POST /token: a 60-minute session bound to this user's records. Returns what the connect window needs. def self.create_session(user_id:, dns_records:) body = { applicationId: ENV.fetch("CNAMIO_APPLICATION_ID"), secret: ENV.fetch("CNAMIO_SECRET"), userId: user_id.to_s, dnsRecords: dns_records } response = Net::HTTP.post(URI.join(API, "/token"), body.to_json, "Content-Type" => "application/json") raise "cnamio #{response.code}" unless response.is_a?(Net::HTTPSuccess) { token: JSON.parse(response.body).fetch("auth_token"), applicationId: ENV.fetch("CNAMIO_APPLICATION_ID"), dnsRecords: dns_records } end # Cnamio-Signature: sha256= of "{Cnamio-Timestamp}.{raw body}", timestamp within 5 minutes. def self.verify_webhook(raw_body, headers, secret = ENV["CNAMIO_WEBHOOK_SECRET"]) timestamp = headers["Cnamio-Timestamp"].to_s return false if secret.blank? || timestamp !~ /\A\d{1,12}\z/ || (Time.now.to_i - timestamp.to_i).abs > 300 expected = "sha256=" + OpenSSL::HMAC.hexdigest("SHA256", secret, "#{timestamp}.#{raw_body}") ActiveSupport::SecurityUtils.secure_compare(expected, headers["Cnamio-Signature"].to_s) end end ``` ## 3. Controllers ```ruby # app/controllers/cnamio_sessions_controller.rb class CnamioSessionsController < ApplicationController before_action :authenticate_user! # your own auth def create render json: Cnamio.create_session(user_id: current_user.id, dns_records: Cnamio.records_for(current_user.id)) rescue StandardError render json: { error: "cnamio_unavailable" }, status: :bad_gateway end end # app/controllers/cnamio_webhooks_controller.rb class CnamioWebhooksController < ActionController::API def create raw = request.raw_post # the raw body: the signature is over these bytes return head :unauthorized unless Cnamio.verify_webhook(raw, request.headers) event = JSON.parse(raw) # Idempotent by event["id"]: the same event may arrive again. case event["type"] when "domain.added" then mark_domain_connected(event["user_id"], event["domain"]) # your code when "domain.propagation.timeout" then mark_domain_failed(event["user_id"], event["domain"]) end head :ok end end ``` ```ruby # config/routes.rb post "/api/cnamio/session", to: "cnamio_sessions#create" post "/webhooks/cnamio", to: "cnamio_webhooks#create" ``` ## 4. Connect button: in a view ```erb ``` ## 5. Register the webhook and check it ```bash 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"}' curl -s -X POST https://api.cnamio.com/v1/manage/webhook-test -u "$CNAMIO_APPLICATION_ID:$CNAMIO_SECRET" # → {"delivered":true} ``` With the test application's credentials every domain goes to the sandbox provider: `shop.example.com` connects at once, `conflict.example.com` shows a conflict, `pending.example.com` never propagates. # Recipe: custom domains in a Laravel app Let the users of a Laravel app connect their own domain with Cnamio: a session route, the connect window in a Blade view, and a webhook route. There is no PHP SDK: this recipe calls the REST API with Laravel's HTTP client, exactly what the Node.js and Python SDKs do. The full guide is https://cnamio.com/agent-onboarding/SKILL.md; every route is in https://cnamio.com/openapi.json. ## 1. Configure ```bash CNAMIO_APPLICATION_ID=app_… CNAMIO_SECRET=cnm_sk_… # server only, never committed CNAMIO_OWNERSHIP_KEY=… # any long random secret of yours CNAMIO_WEBHOOK_SECRET=… ``` ```php // config/services.php 'cnamio' => [ 'application_id' => env('CNAMIO_APPLICATION_ID'), 'secret' => env('CNAMIO_SECRET'), 'ownership_key' => env('CNAMIO_OWNERSHIP_KEY'), 'webhook_secret' => env('CNAMIO_WEBHOOK_SECRET'), ], ``` No account yet? A coding agent can call the MCP tool `start_signup` (or `POST https://api.cnamio.com/v1/agent/signup`) with your email, and work in the sandbox until you open the verification link. ## 2. A small client: `app/Services/Cnamio.php` ```php 'CNAME', 'host' => '{SUBDOMAIN}', 'value' => $target, 'ttl' => 300], ['type' => 'TXT', 'host' => "_{$prefix}.{SUBDOMAIN}", 'value' => "{$prefix}={$value}", 'ttl' => 300], ]; } /** POST /token: a 60-minute session bound to this user's records; returns what the connect window needs. */ public static function createSession(string|int $userId, array $dnsRecords): array { $appId = config('services.cnamio.application_id'); $token = Http::timeout(20)->post('https://api.cnamio.com/token', [ 'applicationId' => $appId, 'secret' => config('services.cnamio.secret'), 'userId' => (string) $userId, 'dnsRecords' => $dnsRecords, ])->throw()->json('auth_token'); return ['token' => $token, 'applicationId' => $appId, 'dnsRecords' => $dnsRecords]; } /** Cnamio-Signature: sha256= of "{Cnamio-Timestamp}.{raw body}", timestamp within 5 minutes. */ public static function verifyWebhook(string $rawBody, ?string $timestamp, ?string $signature): bool { $secret = config('services.cnamio.webhook_secret'); if (!$secret || !preg_match('/^\d{1,12}$/', (string) $timestamp) || abs(time() - (int) $timestamp) > 300) { return false; } $expected = 'sha256=' . hash_hmac('sha256', $timestamp . '.' . $rawBody, $secret); return hash_equals($expected, (string) $signature); } } ``` ## 3. Routes ```php // routes/web.php use App\Services\Cnamio; use Illuminate\Http\Request; Route::post('/api/cnamio/session', function (Request $request) { $user = $request->user(); try { return response()->json(Cnamio::createSession($user->id, Cnamio::recordsFor($user->id))); } catch (\Throwable $e) { return response()->json(['error' => 'cnamio_unavailable'], 502); } })->middleware('auth'); // routes/api.php (no CSRF: Cnamio signs the request instead) Route::post('/webhooks/cnamio', function (Request $request) { $raw = $request->getContent(); // the raw body: the signature is over these bytes if (!Cnamio::verifyWebhook($raw, $request->header('Cnamio-Timestamp'), $request->header('Cnamio-Signature'))) { return response('bad signature', 401); } $event = json_decode($raw, true); // Idempotent by $event['id']: the same event may arrive again. match ($event['type']) { 'domain.added' => markDomainConnected($event['user_id'], $event['domain']), // your code 'domain.propagation.timeout' => markDomainFailed($event['user_id'], $event['domain']), default => null, }; return response('ok'); }); ``` Routes in `routes/api.php` are served under `/api`: register `https://yourapp.com/api/webhooks/cnamio` as the webhook URL. ## 4. Connect button: in a Blade view ```blade ``` ## 5. Register the webhook and check it ```bash 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/api/webhooks/cnamio"}' curl -s -X POST https://api.cnamio.com/v1/manage/webhook-test -u "$CNAMIO_APPLICATION_ID:$CNAMIO_SECRET" # → {"delivered":true} ``` With the test application's credentials every domain goes to the sandbox provider: `shop.example.com` connects at once, `conflict.example.com` shows a conflict, `pending.example.com` never propagates. # Recipe: custom domains in a Django app Let the users of a Django app connect their own domain with Cnamio: a session view, the connect window in a template, and a webhook view. Uses the Python server SDK (`pip install cnamio`, Python 3.9+, standard library only). The full guide is https://cnamio.com/agent-onboarding/SKILL.md. ## 1. Install and configure ```bash pip install cnamio ``` Or vendor the single module instead: `curl -s https://cnamio.com/sdk/cnamio.py -o cnamio.py`. ```bash CNAMIO_APPLICATION_ID=app_… CNAMIO_SECRET=cnm_sk_… # server only, never committed CNAMIO_OWNERSHIP_KEY=… # any long random secret of yours CNAMIO_WEBHOOK_SECRET=… ``` No account yet? A coding agent can call the MCP tool `start_signup` (or `POST https://api.cnamio.com/v1/agent/signup`) with your email, and work in the sandbox until you open the verification link. ## 2. Views: `domains/views.py` ```python import json import os from cnamio import Cnamio, CnamioError, records_for_user, verify_webhook from django.contrib.auth.decorators import login_required from django.http import HttpResponse, JsonResponse from django.views.decorators.csrf import csrf_exempt from django.views.decorators.http import require_POST cnamio = Cnamio() # reads CNAMIO_APPLICATION_ID and CNAMIO_SECRET def records_for(user_id): # A CNAME to your hosting plus a TXT only this user can satisfy. return records_for_user(target="customers.yourapp.com", user_id=user_id, ownership_key=os.environ["CNAMIO_OWNERSHIP_KEY"]) @login_required @require_POST def cnamio_session(request): try: return JsonResponse(cnamio.create_session(user_id=request.user.pk, dns_records=records_for(request.user.pk))) except CnamioError: return JsonResponse({"error": "cnamio_unavailable"}, status=502) @csrf_exempt # signed by Cnamio instead of a CSRF token @require_POST def cnamio_webhook(request): if not verify_webhook(request.body, request.headers, os.environ.get("CNAMIO_WEBHOOK_SECRET")): return HttpResponse(status=401) event = json.loads(request.body) # Idempotent by event["id"]: the same event may arrive again. if event["type"] == "domain.added": mark_domain_connected(event["user_id"], event["domain"]) # your code elif event["type"] == "domain.propagation.timeout": mark_domain_failed(event["user_id"], event["domain"]) return HttpResponse(status=200) ``` ```python # urls.py from django.urls import path from domains import views urlpatterns = [ path("api/cnamio/session", views.cnamio_session), path("webhooks/cnamio", views.cnamio_webhook), ] ``` ## 3. Connect button: in a template ```html ``` ## 4. Headless (management commands, agents) ```python records = records_for(user.pk) check = cnamio.check_domain("shop.customer.com", records) # provider, setupType, connectMethods, conflicts if "api_token" in check["connectMethods"] and provider_token: job = cnamio.connect_automatic("shop.customer.com", records, provider_token, user_id=user.pk) else: job = cnamio.connect("shop.customer.com", records, user_id=user.pk) # exact records to show the user print(cnamio.status(job["job_id"])["status"]) ``` ## 5. Check it With the test application's credentials every domain goes to the sandbox provider: `shop.example.com` connects at once, `conflict.example.com` shows a conflict, `pending.example.com` never propagates. Register the webhook with `cnamio.manage.set_webhook_url("https://yourapp.com/webhooks/cnamio")` and send a signed test with `cnamio.manage.test_webhook()`. ## Custom domains (Cnamio) This project lets its users connect their own domain with Cnamio (https://cnamio.com). When you work on custom domains: - Follow https://cnamio.com/agent-onboarding/SKILL.md. Docs for agents: https://cnamio.com/llms.txt (everything in one file: https://cnamio.com/llms-full.txt). Framework recipes: https://cnamio.com/recipes/nextjs.md, express.md, rails.md, laravel.md, django.md. - Use the server SDK (`npm i cnamio` or `pip install cnamio`) or the REST API at https://api.cnamio.com. MCP server: https://api.cnamio.com/mcp. - Credentials live in the server environment only: `CNAMIO_APPLICATION_ID`, `CNAMIO_SECRET` (never in client code, never committed, never pasted in chat), `CNAMIO_OWNERSHIP_KEY`, `CNAMIO_WEBHOOK_SECRET`. Never invent them. - No credentials yet: run against the sandbox (MCP `start_sandbox`, or `POST https://api.cnamio.com/v1/agent/sandbox`), and offer to start a free account for the developer (MCP `start_signup` or `POST https://api.cnamio.com/v1/agent/signup`, with their email and their agreement to the Terms and Privacy Policy). The account exists only after they open the emailed link. They can also sign up themselves at https://cnamio.com/?utm_source=agents-md&utm_medium=agent#start. - Build DNS records per user with `recordsForUser` / `records_for_user` (a CNAME plus an ownership TXT), bind them to the session, and send the same array to the connect window. - The `domain.added` webhook, verified over the raw body with `CNAMIO_WEBHOOK_SECRET`, is the only signal that a domain is connected. Handle events idempotently by `id`. - Cnamio never deletes or overwrites existing DNS records. Never ask for, store or log a DNS provider password; a provider API token is passed straight to `connect_automatic` and used once. - Test with the test application (sandbox provider): `shop.example.com` connects, `conflict.example.com` conflicts, `pending.example.com` never propagates. # Every DNS provider, two ways to connect. Cnamio finds where a domain's DNS is hosted and takes the best path: it creates the records itself on Cloudflare, Hostinger and Amazon Route 53, and shows the exact records to copy everywhere else. Your integration is the same in both cases. ## Two ways to connect ### Automatic (3 providers) Your user pastes an API token or access key from their DNS provider. Cnamio reads the zone, creates only the records you asked for and discards the credential when the request ends. - Cloudflare - Hostinger - Amazon Route 53 ### Guided (every other provider) The connect window shows each record with its type, name, value and TTL and a copy button. Your user adds them in their own DNS panel; Cnamio keeps checking until they are live. - Registro.br - HostGator - KingHost - Locaweb - Umbler - GoDaddy - any other provider Either way your backend receives the same signed `domain.added` webhook once every required record is live, with `setup_type` set to `automatic` or `manual`. **How a provider becomes automatic.** We list a provider here only after completing a real connection on a real zone through its official API, and checking that the rest of the zone was left exactly as it was. Until then it stays guided. ## How the provider is detected Cnamio looks up the domain's authoritative nameservers and matches them against known provider patterns. Where the domain was bought does not matter: a domain registered at one company with its DNS hosted at Cloudflare is treated as Cloudflare, because that is where the records have to be created. Every nameserver has to belong to the same provider. A mixed or unknown set is treated as "other provider" and gets generic steps that work in any DNS panel, never a guess. Detection only decides the wording and whether a token can be offered; the records shown and the final verification do not depend on it. The DNS zone is found the same way, so public suffixes such as `.com.br` and multi-level names work: for `agenda.meustudio.com.br` in the zone `meustudio.com.br`, your user is asked to create the name `agenda`. ## Automatic setup In the connect window your user sees the provider that was found and a field for the credential, with the steps to create it. From a backend or an agent, pass it to `POST /connect/automatic`. Then, in one request: 1. Cnamio reads the zone with the credential. 2. It compares the records you asked for with what already exists. If something is in the way, nothing is written and the user sees the conflict. 3. It creates only the requested records. 4. The credential is discarded. It is never written to disk, a database or a log. 5. Propagation is checked on every authoritative nameserver until the records are live, and your backend receives the webhook. A user who prefers not to paste a credential can always choose "I'd rather copy the records manually" and follow the guided steps. ### Cloudflare (Automatic) **Credential:** an API token that can edit DNS for the one zone. 1. In the Cloudflare dashboard, open My Profile → API Tokens. 2. Click Create Token and pick the "Edit zone DNS" template. 3. Under Zone Resources, choose only this domain. 4. Create the token, copy it and paste it in the connect window. CNAME records are created as DNS only (not proxied). The token can be deleted as soon as the connection is made. ### Hostinger (Automatic) **Credential:** an API token from hPanel. 1. In Hostinger hPanel, open Account → API. 2. Generate a new token. 3. Copy the token and paste it in the connect window. The token can be deleted in hPanel as soon as the connection is made. ### Amazon Route 53 (Automatic) **Credential:** the access key ID and secret access key of an IAM user made for this, limited to the hosted zone. Temporary keys (`ASIA…`) are not accepted. 1. In the AWS console, open IAM → Users → Create user, without console access. 2. Allow it to edit only this Route 53 zone: `ListHostedZonesByName`, `ListResourceRecordSets` and `ChangeResourceRecordSets`. 3. Under Security credentials, create an access key and paste its ID and secret in the connect window. Use a policy that only allows creating records, and only in one zone. List the record types your application asks for (here, a CNAME and an ownership TXT): ``` { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": "route53:ListHostedZonesByName", "Resource": "*" }, { "Effect": "Allow", "Action": "route53:ListResourceRecordSets", "Resource": "arn:aws:route53:::hostedzone/ZONE_ID" }, { "Effect": "Allow", "Action": "route53:ChangeResourceRecordSets", "Resource": "arn:aws:route53:::hostedzone/ZONE_ID", "Condition": { "ForAllValues:StringEquals": { "route53:ChangeResourceRecordSetsActions": ["CREATE"], "route53:ChangeResourceRecordSetsRecordTypes": ["CNAME", "TXT"] } } } ] } ``` Route 53 itself refuses a `CREATE` for a record that already exists, so an existing record cannot be overwritten. ## Guided setup For every other provider, and whenever a user prefers not to use a credential, the window shows what to create: - Each record with type, name, value and TTL (and priority for MX), each field with its own copy button. - The name is relative to the zone (`shop`, not `shop.customer.com`), which is what most DNS panels ask for. - After "I've added the records", the window waits and checks. Your user can close it: the connection continues on its own for up to 72 hours. Public step-by-step guides for [Registro.br](https://cnamio.com/guides/add-cname-registro-br), [Hostinger](https://cnamio.com/guides/add-cname-hostinger), [Locaweb](https://cnamio.com/guides/add-cname-locaweb), [HostGator and KingHost](https://cnamio.com/guides/add-cname-hostgator-kinghost), [Cloudflare](https://cnamio.com/guides/add-cname-cloudflare) and [GoDaddy](https://cnamio.com/guides/add-cname-godaddy), in English, Portuguese and Spanish, and a free [CNAME checker](https://cnamio.com/tools/cname-checker) that reads the authoritative nameservers. To see what your users would see for a given domain, try the [live demo](https://cnamio.com/demo). When the nameservers match a provider we know, the window names it. With `locale: "pt-BR"`, `POST /checkdomain` and `POST /connect` also return `instructions`: the steps in that provider's own panel, in Portuguese, for a single CNAME. **Adding a CNAME by hand at Cloudflare.** It has to be set to "DNS only". With the proxy on, the CNAME is not visible in DNS and the verification cannot complete. To always show the guided steps, even for a provider with automatic setup, open the window with `forceManualSetup: true` and a `prefilledDomain`. ## Existing records are never deleted Cnamio adds records, and the only existing one it can change is an SPF policy (extended, every term kept). Before writing it reads what exists and applies the same rules for every provider: - A CNAME needs a free name: it is not created next to any other record with that name. - A, AAAA and MX records are never added next to different existing values. - TXT and CAA values are added next to existing ones, except a second DMARC policy or a second DKIM key at the same selector. - A domain can publish only one SPF policy, so a requested one is merged into the existing policy: every existing term stays as it is and only the missing mechanisms are added before `all`. The user gets the full merged value to paste; where the merge is enabled for the provider, Cnamio edits that one record. It is refused when the result would pass 10 DNS lookups. - Names covered by a wildcard, delegated to another server, proxied or aliased by the provider are left for a person to review. When something is in the way the API answers `409` with the list of conflicts and nothing is written. In the window, the user sees what already exists and can use another address or adjust that record at the provider. ## What your code sees `POST /checkdomain` tells you the provider and the path before you start. `connectMethods` contains `api_token` when the records can be created with the user's credential: ``` { "domain": "shop.customer.com", "zone": "customer.com", "provider": "route53", "setupType": "Automatic", "connectMethods": ["api_token"], "nameservers": ["…"] } ``` The same `provider` and the `setup_type` come back in the connection status and in the webhook, so you can show your user where their DNS is and how the domain was connected. Details in the [REST reference](https://cnamio.com/docs#rest). ## Need another provider to be automatic? Guided setup already works with it today. If many of your users keep their DNS at one provider, tell us which at [contato@cnamio.com](mailto:contato@cnamio.com): that is how we choose what to test next. --- This is the Markdown of https://cnamio.com/providers. Every page for agents: https://cnamio.com/llms.txt # Built to be trusted with someone else's DNS. Your users give Cnamio access to something they cannot afford to break. These are the rules the service is built on, and what happens to every credential and piece of data involved. ## Existing DNS is never deleted Cnamio only adds the records your application asks for. It has no operation that removes a record that was already in the zone, and the only existing record it can change is an SPF policy, which it extends without dropping anything. - The zone is read first. If a requested record would collide with something that exists, nothing is written: the API answers `409` with the conflicts, and the user decides what to do at their provider. - A CNAME is created only at a free name. A, AAAA and MX are never added next to different existing values. TXT and CAA values are added next to existing ones, except a second DMARC policy or a second DKIM key at the same selector. - A domain can publish only one SPF policy, so a requested one is merged into the existing policy: every existing term stays as it is, in its place, and only the missing mechanisms are added before `all`. The merge is refused if the result would pass 10 DNS lookups. The user gets the merged value to paste; the automatic edit is enabled per DNS provider. - Disconnecting is yours to do: stop serving the domain in your app and tell the user they may remove the records. Cnamio never deletes them. The rules for each provider are on the [providers page](https://cnamio.com/providers#conflicts). ## Provider credentials are used once Cnamio never asks for the password of a DNS provider account. For automatic setup the user pastes an API token or access key, and that credential: - is used during that single request, to read the zone and create only the requested records; - is never written to disk, a database or a log; - is discarded when the request ends. We show users how to create a credential with the smallest scope the provider allows, such as a Cloudflare token for one zone or an AWS policy that can only create records in one hosted zone, and they can delete it right after connecting. If you pass a provider token through your own backend, do not store or log it either. ## Your secret stays on your server - Each application has an id (`app_…`) and a secret (`cnm_sk_…`). The secret is shown once and we keep only a one-way hash of it. - Browsers never see the secret. They receive a session token that lasts 60 minutes and can be bound to one user, one domain and one exact list of records, so a page cannot change the target of a connection. - `POST /token` and the management API never answer cross-origin browser requests. - A secret can be rotated at any time; the old one keeps working for a grace period (24 hours by default) so you can deploy the new one without downtime. ## One user cannot claim another user's domain When all of your users point their domains at the same CNAME target, a CNAME that already exists proves nothing about who started the connection. Cnamio lets you require a TXT record whose value is unique to each user, built on your server and bound to the session token. `domain.added` is sent only when every required record is live, so only someone who controls that domain's DNS can complete the connection. The server SDKs build these records with `recordsForUser`. ## Verified at the source A connection is confirmed by asking every authoritative nameserver of the domain, not a public resolver that may hold a cached answer. A domain is reported as connected only when all required records are live on all of them. Checks run for up to 72 hours; after that your backend receives `domain.propagation.timeout` instead of silence. Once a domain is connected, monitoring keeps asking the same nameservers on a slow schedule (hourly, then every 6 hours, then daily). It only reads DNS: it never creates, changes or removes a record. ## Signed webhooks - Every delivery carries `Cnamio-Signature`, an HMAC-SHA256 of `"{timestamp}.{raw body}"` with a signing secret only your application can read, plus `Cnamio-Timestamp` and `Cnamio-Event-Id`. - Reject timestamps older than 5 minutes and treat the event id as an idempotency key: a delivery that is not answered with `2xx` is retried after 1, 5 and 30 minutes. - Webhook URLs must be public HTTPS addresses. Private and internal addresses are refused and redirects are not followed. The verification function is in the [docs](https://cnamio.com/docs#webhooks) and in both server SDKs. ## The connect window is isolated The window runs in an iframe served from Cnamio's origin with its own Content-Security-Policy. Its configuration, session token included, reaches it only through `postMessage` and never in a URL. On the page that opens it you only need to allow `https://connect.cnamio.com` in `script-src` and `frame-src`. ## Data and privacy - **What a connection stores:** the domain, the records you asked for, the DNS provider recognized from the nameservers, the result of each propagation check, timestamps and the user identifier you choose to send. - **Errors and logs:** errors are a fixed text and never echo request contents; operational logs hold fixed status codes, never request bodies or tokens. - **Where:** our servers and database run in Brazil. The full list of providers involved is in the privacy policy. - **This site:** no cookies and no third-party scripts, served with a strict Content-Security-Policy. Page views are counted by a script of our own that stores no IP address and records nothing under Do Not Track or Global Privacy Control; the privacy policy has the details. - **Limits:** by default 60 requests per minute per address and per session, under a ceiling of 600 per application. Cnamio is a young service and does not hold a third-party security certification today. The [Privacy Policy](https://cnamio.com/privacy) describes our role under Brazil's LGPD and the EU GDPR, retention and your rights; the [Terms of Service](https://cnamio.com/terms) cover the rest. ## Report a security problem Write to [contato@cnamio.com](mailto:contato@cnamio.com) with what you found and the steps to reproduce it. Please test only with domains and applications that are yours. --- This is the Markdown of https://cnamio.com/security. Every page for agents: https://cnamio.com/llms.txt