Docs · API reference

Developer docs

Session tokens, the connect window, DNS records, REST endpoints, signed webhooks, the management API, server SDKs and the MCP server. New here? Start with the quickstart.

Also as Markdown · OpenAPI 3.1 · llms.txt

Overview

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.

Base URLs: API https://api.cnamio.com, SDK https://connect.cnamio.com/sdk/v1.js. Each integration is an application with an applicationId (app_…) and a secret (cnm_sk_…, shown once). Keep the secret on your server.

1. Create a session token on your server

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. /token never answers browser (CORS) requests.

2. Open the connect window in your page

<script src="https://connect.cnamio.com/sdk/v1.js"></script>
<script>
  cnamio.connectDomain({
    applicationId: 'app_…',
    token: SESSION_TOKEN,           // auth_token from step 1
    applicationName: 'Your App',    // shown in the window
    locale: 'en',                   // 'pt-BR', 'en' or 'es' (also 'en-US', 'es-MX'…)
    userId: 'user-42',
    prefilledDomain: 'shop.example.com', // optional
    dnsRecords: [
      { type: 'CNAME', host: '{SUBDOMAIN}', value: 'app.yourproduct.com', ttl: 300 },
      { type: 'TXT', host: '_verify.{SUBDOMAIN}', value: 'token=abc123' },
    ],
  });

  window.addEventListener('onCnamioSuccess', e => console.log(e.detail.jobId));
  window.addEventListener('onCnamioClose', e => console.log(e.detail.lastStatus));
  window.addEventListener('onCnamioStepChange', e => console.log(e.detail.step));
</script>

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}, {SUBDOMAIN}, {SLD}, {TLD}; @ is the zone apex. {DOMAIN} is the domain's real DNS zone, so agenda.meustudio.com.br in zone meustudio.com.br gives {SUBDOMAIN} = agenda. 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. 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. See how each provider works.

Existing records are never deleted. A CNAME needs a free name; A, AAAA and MX are never added next to different existing values (an existing MX is never replaced); TXT and CAA values are added next to existing ones, except a second DMARC policy (dmarc_exists) or a second DKIM key at the same selector (dkim_selector_exists). When something is in the way, the user sees what already exists and decides.

Email records. A domain can publish only one SPF policy, so a requested SPF is merged into the existing one instead of becoming a second record: every existing term is kept as it is, in its place, including the all qualifier, and only the missing mechanisms are added just before all. If the existing policy already authorizes them, nothing is written and the record counts as present. The merge is refused, with a reason, when the name has more than one SPF policy (spf_multiple_records), the request has two (spf_multiple_requested), the existing policy cannot be read safely (spf_unparseable), the requested one has modifiers such as redirect= (spf_merge_unsupported), or the result would pass 10 DNS-lookup terms (spf_lookup_limit, counted on the merged record itself) or 450 characters (spf_too_long). With checkConflicts, /checkdomain returns recordMerges with the full merged value and the policy it replaces; the connect window asks the user to edit the existing record with that value. Unless the request sends acceptMerges: true, each merge is also listed in recordConflicts as spf_merge_required, with the merged value in merge, so a client that builds its own instructions never asks for a second SPF record. POST /connect returns the same recordMerges, and merge on the SPF record. The automatic path answers 409 with spf_merge_required unless the merge is enabled for that DNS provider, and Domain Connect is not offered when a merge is needed. A connection with an SPF record is verified (and monitored) when the name has exactly one policy authorizing the requested mechanisms.

REST endpoints

Send Authorization: Bearer <auth_token> and applicationId: app_…. These endpoints answer CORS, so they can be called from your page with the session token.

EndpointWhat it does
POST /checkdomain{ domain, dnsRecords, checkConflicts? } → DNS provider, setupType (Automatic or Manual), 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 /connectManual 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. 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, and webhook.test when you send a test from the dashboard. 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, Cnamio-Event-Id and Cnamio-Signature: sha256=<hex>, an HMAC-SHA256 of "{timestamp}.{raw body}" with your signing secret (dashboard → Webhook → Reveal secret). Reject timestamps older than 5 minutes.

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()). Failed deliveries are retried after 1, 5 and 30 minutes. 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).

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.

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.

EndpointWhat it does
GET /v1/manage/applicationName, webhook URL and settings of the application.
PUT /v1/manage/webhook{ url } (HTTPS) or null to stop deliveries.
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-secretThe secret that signs your webhooks.
POST /v1/manage/webhook-testSends 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/jobsRecent 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}/revokeList (never the tokens), read, revoke.
GET /v1/manage/usage?month=YYYY-MMConnections started, completed and expired, and billable domains: each connected domain counts once per month.

Server SDKs

One file each, no dependencies, for your backend: cnamio.mjs for Node.js 18+ (types: cnamio.d.mts) and cnamio.py for Python 3.9+. Save the file in your project and import it. They create sessions, check and connect domains, read status, call the management API, build per-user ownership records and verify webhooks.

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

MCP server (for AI agents)

Agents can use Cnamio directly as tools through https://api.cnamio.com/mcp (Streamable HTTP): get_integration_guide (no credentials), check_domain, connect_domain, connect_domain_automatic, get_connection_status, recheck_propagation, list_connections, create_share_link and revoke_share_link. They behave exactly like the REST routes. Authenticate with the application credentials as HTTP Basic, or a session token as Bearer plus an applicationId header. Coding agents can also follow the integration skill; everything is indexed in llms.txt. More on the agents page.

{
  "mcpServers": {
    "cnamio": {
      "url": "https://api.cnamio.com/mcp",
      "headers": { "Authorization": "Basic <base64 of applicationId:secret>" }
    }
  }
}

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 provider token is accepted except invalid (422). A domain whose first label is conflict has a foreign CNAME at every name (409); one starting with pending never shows its records. Test applications start up to 100 domains per month (then 429, sandbox_limit_reached).

The live application has a plan with a monthly allowance: 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 answer 402 with { message, code: "plan_limit_reached", plan, limit, used, resets_at }; connected domains keep working. At 80% your webhook receives one signed usage.quota_warning event and the account gets an email. See the plans.

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; ask your server for a new one when needed.

Questions or access: contato@cnamio.com.