Skip to content

Domains and internal DNS connections ​

The module manages hostname ownership and access to the DNS zones authorized for NimoApps. It only accepts a user session with a live OWNER/ADMIN role for the active company. The operations are not available to API keys, integration OAuth, app clients, the public SDK, external MCP or the embeddable chat.

When a hostname is registered, the backend normalizes IDNs to lowercase ASCII and issues a random TXT challenge. Ownership only becomes verified when exactly that value is found; a pre-existing CNAME does not count. After verification the challenge is removed and the hostname is registered on the Pages project before DNS is considered ready. The same operation re-reads the Pages state, so pending propagation and TLS can be retried without repeating the TXT. DNS is verified only with active Pages validation, and TLS only once Pages, DNS and the certificate are active. Failures persist as safe states; CAA restrictions answer APP_DOMAIN_TLS_CAA_RESTRICTION. Active hostnames are unique across the whole platform, although a conflict does not reveal which tenant already uses one.

Recoverable withdrawal ​

Disconnecting a domain is not a simple state change. Withdrawal first disables the route at the provider and waits for confirmation, then deletes only the DNS records Nimobase created (tagged by the provider) for that hostname inside the zone the company delegated, and only then releases the hostname. Customer records, provider-owned types and any undelegated zone are never touched; if the connection was revoked, the cleanup resolves as skipped instead of guessing.

Each step is persisted before the next one runs, so a mid-way failure is visible and retryable: the API answers 503 with a stable code and the operation identifier, the hostname stays reserved, and repeating the deletion resumes from the first pending step. An already confirmed withdrawal is idempotent and does not call the provider again. While the hostname is reserved nobody can claim it, so a partial failure does not allow takeover by third parties. GET /app-domains/:id/withdrawal shows the persisted steps, whether the hostname is still reserved and whether it can be retried, without contacting the provider.

Transfer reuses those same steps for the previous assignment and then moves the domain to another environment of the same company with a new TXT challenge: ownership is proven again and a failure leaves the domain in its original environment, retryable.

The DNS connection receives a Cloudflare token, checks access to the named account and stores the token encrypted with the shared AES-GCM vault. Responses show account metadata only. Zone lookups use the explicit account, filter out any response from another account and confirm again that the connection is still active. Revoking the connection deletes the ciphertext and detaches the linked domains transactionally.

MethodRouteResult
POST/app-domainsRegisters the hostname and returns the TXT challenge
GET/app-domainsLists the current company's active domains
GET/app-domains/:idReads one of the tenant's domains
POST/app-domains/:id/ownership/verifyVerifies the TXT and updates Pages, DNS and TLS
POST/app-domains/:id/transferWithdraws the previous assignment and issues a new challenge
GET/app-domains/:id/withdrawalShows withdrawal steps and whether the hostname is reserved
DELETE/app-domains/:idRecoverable withdrawal; releases the hostname on confirmation
POST/app-dns-connectionsValidates and connects a DNS account
GET/app-dns-connectionsLists safe connection metadata
GET/app-dns-connections/:id/zonesReturns that account's authorized zones
DELETE/app-dns-connections/:idRevokes the token and detaches active references
GET/app-dns-connections/:id/zones/:zoneId/recordsLists records with revision and protection
POST/app-dns-connections/:id/zones/:zoneId/records/previewReviews the diff without writing
POST/app-dns-connections/:id/zones/:zoneId/recordsCreates a permitted record
PUT/app-dns-connections/:id/zones/:zoneId/records/:recordIdChanges the record when the revision matches
DELETE/app-dns-connections/:id/zones/:zoneId/records/:recordIdDeletes when the revision matches

A Pages apex requires an active zone in the same Cloudflare account as the project and nameservers delegated to Cloudflare; the backend rejects any other account and explains the requirement. A subdomain with external DNS can use a CNAME. The backend never manages nameservers, zones or DNSSEC: it only edits individual records inside a zone the company delegated.

Revisioned DNS record editing ​

The company can create, change and delete A, AAAA, CNAME, TXT, MX and CAA records in an authorized zone. Before writing, the name is validated against the zone, the value against the type, the TTL and the MX priority; an invalid value returns a stable error and produces no write. Provider NS, SOA and DNSSEC records are shown as non-editable and are never modified, and no other records (for example existing mail) are touched as a side effect.

Every record carries a revision: a change or a deletion only applies when the revision is still the one that was reviewed, so two people cannot overwrite each other. Preview returns the before/after with the diff and writes nothing, so Nimo can show the change before confirming. Repeating the same creation or deletion neither duplicates nor fails: it converges without writing. Every applied write returns the before/after and its audit entry, and records created from Nimobase are marked as owned.

A Pages domain's hostname and the ownership-verification TXT are protected: they are changed from the domain card, not from the DNS zone. Internal Nimo uses app-dns-connections.records.list|preview|create|update|delete with the nimo:application-dns:records:read|write scopes; none of this is available in public widgets, the public SDK or external MCP.

Internal Nimo reads readiness with app-domains.pages.readiness, which only reads the stored state and returns ready with a single next step (PROVE_OWNERSHIP, REGISTER_IN_PAGES, RETRY_PAGES_REGISTRATION, WAIT_DNS_PROPAGATION, FIX_DNS_RECORDS, WAIT_TLS_ISSUANCE, FIX_TLS_CONFIGURATION or ACTIVE). ready requires verified ownership, Pages record, DNS and TLS: a CNAME that resolves is not enough, and a failed certificate never activates the domain. Pending propagation resumes by repeating the read or the ownership verification. It can also read the withdrawal with app-domains.withdrawal.get, which exposes the durable steps and requires the internal nimo:application-domains:withdrawal:read scope. None of these capabilities is available in public widgets, the public SDK or external MCP.