Custom Domain APIs

The DNS page manages two domain types:

• External domains: user enters any valid FQDN and proves control with a TXT record.
• Free subdomains: user claims a subdomain under a configured free-domain namespace.

External domains are inactive until the TXT record is confirmed. File hosting and mail forwarding are enabled independently based on the A/MX/TXT records that resolve during refresh.

Authentication

Every /api/dns/* endpoint requires a primary cookie session. JSON write routes require Content-Type: application/json.

Sharing

Open an owned domain in the Domains/DNS tab and invite an existing username. The recipient sees the invitation in the same tab and explicitly accepts or refuses it. Usernames are case-insensitive. Pending invitations expire after 30 days and grant no access. Owners can cancel invitations and revoke members; members can leave. A refused invitation cannot be sent again for 24 hours.

Accepted members can publish their own files and create individual email aliases on the domain when the corresponding service is active. Shared domains appear in the normal upload/paste/download and mail domain selectors. Each account keeps its own storage quota, files, and email aliases. Sharing does not grant access to anyone else’s files or mail, catch-all forwarding, parent DNS, branding, SSL, aliases, subdomain claims, ownership, or inviting other users.

Revoking or leaving stops new publication and new email aliases; it does not delete existing files or email aliases. The uploader can still download, delete, or move their files to another permitted host, and can delete their own mail aliases. Republishing on the shared domain requires current access. If the domain loses hosting or is deleted, its members’ files move to the safe host alongside the owner’s files; file ownership is preserved. Restoration only restores files for the owner and current accepted members.

GET /api/dns/domains returns domains (owned domains), invitations (pending), and sharedDomains (accepted). Shared entries expose the hostname, usernames, invitation dates/status, and active services, but no verification keys, account tokens, private DNS records, or other users’ member lists.

Sharing writes require a primary session and JSON. Browser requests must originate from the HTTPS main host. Limits: 30 new invitations per owner per day, 50 pending or accepted members per domain, and 100 pending or accepted shares per recipient. Domain-wide file paths (index, index.*, 404, robots.txt, favicon.ico, and configured not-found paths) remain reserved for the owner. Sharing does not allow members to create subdomains. The owner list shows all current members/invitations and recent history, up to 200 entries.

External Domain Create

{
  "type": "external",
  "domain": "files.example.com"
}

Response includes a required TXT record:

{
  "domain": {
    "domain": "files.example.com",
    "domain_type": "external",
    "active": false,
    "requiredRecords": {
      "verification": {
        "type": "TXT",
        "host": "@",
        "value": "axfile-verification-key xxxxxxxxxx"
      }
    }
  }
}

DNS Import

Open an external domain and use BIND zone beside its required DNS records. The download includes its verification TXT, file-hosting addresses, MX, SPF, DKIM and DMARC records, with $ORIGIN set to that domain and a 3600-second TTL. It works before verification, and uses the current server configuration.

Import it into the matching zone at your DNS provider. Both file and mail services are included; omit records for services you do not want, and review existing MX/SPF records before importing. This is a required-records import, not a backup of your existing DNS zone: it does not replace nameservers or include SOA, custom records, or file aliases. Managed free subdomains do not need this import. Only the domain owner can download it, not shared members.

Free Subdomain Create

{
  "type": "free_subdomain",
  "subdomain": "demo",
  "baseDomain": "kt.ci"
}

Free subdomains do not require TXT verification.

Free subdomains can also keep custom DNS records. Managed file/mail records are controlled by the service toggles; custom records are created and deleted separately.

SSL Generation

POST /api/dns/domains/:id/ssl is available after the domain is active and file-hosting DNS is ready. The route refreshes DNS before provisioning. If the A record is missing or ownership is no longer valid, it returns 400 and stores ssl_status: "dns_not_ready".

When DNS is ready, the server requests certificate provisioning and updates the saved SSL status.