Organizations

Verify domain ownership via DNS TXT

Looks up TXT at `_mudbase-verify.<hostname>` for value `mudbase-domain-verification=<token>`. When the server has **`CLOUDFLARE_API_TOKEN`** and **`CLOUDFLARE_ZONE_ID`** configured (and Fly ACME is **not** enabled), a successful verify also creates or refreshes a Cloudflare Custom Hostname (SSL for SaaS) and returns **`cloudflare`** with DCV hints. When **Fly ACME** is enabled (**`FLY_API_TOKEN`** + **`CUSTOM_DOMAIN_FLY_ACME_ENABLED=true`** + app slug), a successful verify calls Fly’s Certificates API (`POST .../certificates/acme`) and persists DNS requirements. If Fly returns DNS rows and **`CUSTOM_DOMAIN_FLY_LEGACY_STAFF_PIPELINE`** is **not** set, status advances to **`cname_approved`** in the same response (no staff **`approve-cname`**); **`org.domain.cname_staff_queued`** is not logged for that path. Otherwise (legacy Fly or non-Fly), first success from `pending`/`failed` may move to **`cname_pending_staff`** and queue staff as before. The **200** response may include **`dnsRecords`**, **`flyCertificateStatus`**, and **`routingCnameTarget`** from Fly’s **`dns_requirements.cname`** when provisioned. Cloudflare SaaS and Fly ACME cannot both be enabled; the API process refuses to start if both are configured.

AuthBearer (JWT)

GroupOrganizations

Rate limitSee Rate Limits

POST/api/orgs/{orgId}/projects/{projectId}/domains/{hostname}/verify-dns

SDK setup

Create a client and set credentials (JWT and/or API key) before calling the API. Match the authentication type shown above.

import { Configuration, OrganizationsApi } from 'mudbase-sdk';

const configuration = new Configuration({
  basePath: 'https://cloud.mudbase.dev',
  accessToken: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJ1c3JfbW9yZ2FuX2RlIiwiZW1haWwiOiJtb3JnYW4uY2hlbkBub3J0aHdpbmQuZGV2IiwiZXhwIjoxODI1MTI5NjAwfQ.doc_preview_sig',
});

const organizations = new OrganizationsApi(configuration);
import { Configuration, OrganizationsApi } from 'mudbase-sdk';

const configuration = new Configuration({
  basePath: 'https://cloud.mudbase.dev',
  accessToken: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJ1c3JfbW9yZ2FuX2RlIiwiZW1haWwiOiJtb3JnYW4uY2hlbkBub3J0aHdpbmQuZGV2IiwiZXhwIjoxODI1MTI5NjAwfQ.doc_preview_sig',
});

const organizations = new OrganizationsApi(configuration);

Example request

Call this endpoint using the client from SDK setup. Use View HTTP for a raw cURL example.

const { data: result } = await organizations.verifyOrgCustomDomainDns("org_T6QGaEAH9V", "proj_n3WS5f2hAnIY", "Kristofer Schneider-Hansen");
const { data: result } = await organizations.verifyOrgCustomDomainDns("org_T6QGaEAH9V", "proj_n3WS5f2hAnIY", "Kristofer Schneider-Hansen");

Playground

live

Test this endpoint with your own credentials. Your requests will be sent to the live API.

JWT Bearer Token Use the auth endpoints to obtain a JWT.

Path Parameters

orgId

projectId

hostname

No Request Yet

Send a request to see the full inspector

Authentication

Requires JWT

Note

Include your JWT in the Authorization: Bearer YOUR_TOKEN header (user-facing apps, RBAC). View authentication guide →

Path Parameters

Name	Type	Required	Description
`orgId`	string	Yes	—
`projectId`	string	Yes	—
`hostname`	string	Yes	—

Responses

200TXT verified. Fly ACME (default automation): often `cname_approved` when Fly returns DNS requirements; legacy Fly or non-Fly may show `cname_pending_staff` or `dns_verified`. Includes `dnsTxtHost`/`dnsTxtValue`, optional `cloudflare` (Cloudflare SaaS), optional `dnsRecords` + `flyCertificateStatus` when Fly ACME ran after this verify.

json

{
  "success": true,
  "hostname": "Loma Rutherford",
  "status": "bus override",
  "verificationToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJ1c3JfZGVtbyJ9.sig_sample",
  "challengeHost": "pixel program",
  "expectedTxt": "bandwidth override",
  "dnsTxtHost": "application calculate",
  "dnsTxtValue": "monitor reboot",
  "cloudflare": {
    "saasIntegrationEnabled": false,
    "skipped": false,
    "reason": "feed bypass",
    "customHostnameId": "Dr. Paris Volkman",
    "hostnameStatus": "Mr. Lafayette Klocko",
    "sslStatus": "array override",
    "ownershipVerification": {
      "name": "Benny Streich",
      "type": "system connect",
      "value": "bandwidth transmit"
    },
    "sslValidationRecords": [
      {
        "txtName": "Lois Bernier",
        "txtValue": "program compress",
        "httpUrl": "https://compassionate-willow.com",
        "httpBody": "interface calculate",
        "cname": "Chad Keebler",
        "cnameTarget": "Mae Dooley"
      }
    ],
    "lastError": "bandwidth input",
    "instructions": "interface synthesize"
  },
  "dnsRecords": [
    {
      "type": "array navigate",
      "name": "Vince Dicki",
      "value": "array parse",
      "purpose": "card back up"
    }
  ],
  "flyCertificateStatus": "sensor program",
  "flyAcmeEnabled": true,
  "flyAcmeDisabledReason": "feed synthesize",
  "flyProvisionError": "card program",
  "flyLegacyStaffPipeline": false
}
{
  "success": true,
  "hostname": "Loma Rutherford",
  "status": "bus override",
  "verificationToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJ1c3JfZGVtbyJ9.sig_sample",
  "challengeHost": "pixel program",
  "expectedTxt": "bandwidth override",
  "dnsTxtHost": "application calculate",
  "dnsTxtValue": "monitor reboot",
  "cloudflare": {
    "saasIntegrationEnabled": false,
    "skipped": false,
    "reason": "feed bypass",
    "customHostnameId": "Dr. Paris Volkman",
    "hostnameStatus": "Mr. Lafayette Klocko",
    "sslStatus": "array override",
    "ownershipVerification": {
      "name": "Benny Streich",
      "type": "system connect",
      "value": "bandwidth transmit"
    },
    "sslValidationRecords": [
      {
        "txtName": "Lois Bernier",
        "txtValue": "program compress",
        "httpUrl": "https://compassionate-willow.com",
        "httpBody": "interface calculate",
        "cname": "Chad Keebler",
        "cnameTarget": "Mae Dooley"
      }
    ],
    "lastError": "bandwidth input",
    "instructions": "interface synthesize"
  },
  "dnsRecords": [
    {
      "type": "array navigate",
      "name": "Vince Dicki",
      "value": "array parse",
      "purpose": "card back up"
    }
  ],
  "flyCertificateStatus": "sensor program",
  "flyAcmeEnabled": true,
  "flyAcmeDisabledReason": "feed synthesize",
  "flyProvisionError": "card program",
  "flyLegacyStaffPipeline": false
}

400dns_verification_failed (TXT missing or wrong); body includes dnsTxtHost, dnsTxtValue, challengeHost, expectedTxt

json

{
  "success": true,
  "code": "dns_verification_failed",
  "error": "program back up",
  "challengeHost": "pixel program",
  "expectedTxt": "bandwidth override",
  "dnsTxtHost": "application calculate",
  "dnsTxtValue": "monitor reboot",
  "status": "bus override",
  "verificationToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJ1c3JfZGVtbyJ9.sig_sample"
}
{
  "success": true,
  "code": "dns_verification_failed",
  "error": "program back up",
  "challengeHost": "pixel program",
  "expectedTxt": "bandwidth override",
  "dnsTxtHost": "application calculate",
  "dnsTxtValue": "monitor reboot",
  "status": "bus override",
  "verificationToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJ1c3JfZGVtbyJ9.sig_sample"
}

503dns_lookup_error

Errors

Code	Meaning
`400`	dns_verification_failed (TXT missing or wrong); body includes dnsTxtHost, dnsTxtValue, challengeHost, expectedTxt
`503`	dns_lookup_error

Run in Postman Download OpenAPI

NEXT →API Reference OverviewBase URL, rate limits, pagination, and the full endpoint index.NEXT →AuthenticationAPI keys, Bearer tokens, and user sessions.NEXT →API PlaygroundSearch any endpoint and send a live request.

Edit this page on GitHub

SDK setup

Example request

Playground

No Request Yet

Authentication

Path Parameters

Responses

Errors

Next