Automatic DNS

Overview

The Automatic DNS API operates only on existing TenantCore domain resources. You cannot submit an arbitrary domain or Microsoft tenant and ask TenantCore to modify it. The required ownership chain is:

API key
  → TenantCore account UUID
    → TenantCore domain_id
      → parent TenantCore tenant
        → Microsoft / DNS provider operation

If the domain does not exist in TenantCore, or its parent tenant belongs to another account, the API returns 404 domain_not_found before any DNS-provider action is attempted.

Automatic DNS is currently supported through TenantCore’s direct Porkbun, Cloudflare, and Namecheap integrations. DNS-provider credentials are connected and managed inside the TenantCore application; this public API does not accept raw registrar credentials.

All write requests require an Idempotency-Key. Live planning/readiness calls perform external DNS/provider reads and therefore use the public API’s expensive rate-limit bucket.

Get stored DNS state

Returns TenantCore’s most recently stored DNS/authentication state for an owned domain.

GET /v1/domains/{domain_id}/dns

domain_id is the TenantCore domain-row UUID returned by the domain APIs. It is not a domain name.

curl https://api.tenantcore.io/v1/domains/DOMAIN_UUID/dns \
  -H "Authorization: Bearer tc_live_your_key"

Example response:

{
  "domain_id": "DOMAIN_UUID",
  "tenant_resource_id": "TENANTCORE_TENANT_UUID",
  "tenant_id": "MICROSOFT_TENANT_GUID",
  "domain_name": "mail.example.com",
  "is_default": false,
  "is_verified": true,
  "dkim_enabled": true,
  "dns_status": {
    "mx": "...mail.protection.outlook.com...",
    "spf": "v=spf1 include:spf.protection.outlook.com -all",
    "dmarc": "v=DMARC1; p=quarantine; ...",
    "dkim": "..."
  },
  "verification_dns_records": [],
  "service_configuration_records": [],
  "dkim_dns_records": [],
  "last_checked": "2026-09-27T20:00:00Z"
}

This endpoint reads stored state. Use Build a live DNS plan when you need a fresh public-DNS/provider comparison.

Build a live DNS plan

Performs a fresh provider-neutral DNS read and compares the domain with TenantCore’s required Microsoft 365 records.

GET /v1/domains/{domain_id}/dns/plan

curl https://api.tenantcore.io/v1/domains/DOMAIN_UUID/dns/plan \
  -H "Authorization: Bearer tc_live_your_key"

The response includes:

detected authoritative DNS provider
desired records
observed records
create/update/preserve/conflict actions
whether the DNS read is reliable
blocking changes that prevent automatic completion

This is a read-only operation. It does not change DNS.

Check automatic-DNS readiness

Checks whether TenantCore can safely apply the current plan through the connected provider.

GET /v1/domains/{domain_id}/dns/automation

curl https://api.tenantcore.io/v1/domains/DOMAIN_UUID/dns/automation \
  -H "Authorization: Bearer tc_live_your_key"

The automation object tells you whether:

the provider is supported for direct API automation
the account has the required provider connection
the current changes are safe to apply
manual action or conflict resolution is required first

A provider connection is always resolved from the authenticated TenantCore account. It cannot be supplied or borrowed from another account through this endpoint.

Start automatic provisioning

Queues TenantCore’s persistent DNS provisioning workflow for one owned domain.

POST /v1/domains/{domain_id}/dns/provision

curl -X POST \
  https://api.tenantcore.io/v1/domains/DOMAIN_UUID/dns/provision \
  -H "Authorization: Bearer tc_live_your_key" \
  -H "Idempotency-Key: dns-provision-mail-example-001"

Successful requests return 202 Accepted.

{
  "domain_id": "DOMAIN_UUID",
  "run": {
    "id": "RUN_UUID",
    "status": "queued",
    "total_domains": 1,
    "created_at": "2026-09-27T20:00:00Z",
    "started_at": null,
    "completed_at": null,
    "updated_at": null
  },
  "jobs": [
    {
      "id": "JOB_UUID",
      "run_id": "RUN_UUID",
      "domain_id": "DOMAIN_UUID",
      "tenant_id": "MICROSOFT_TENANT_GUID",
      "domain_name": "mail.example.com",
      "stage": "queued",
      "status": "queued",
      "provider": null,
      "action_required_code": null,
      "message": null,
      "next_attempt_at": "2026-09-27T20:00:00Z"
    }
  ]
}

Provisioning continues asynchronously through TenantCore’s existing worker. Depending on the current state, the job may move through Microsoft verification, public-DNS propagation, DKIM publication, DKIM enablement, and final health validation. Only one active automatic provisioning job may exist for a domain at a time. Starting another while one is active returns 409 domain_provisioning_already_active.

Get a provisioning run

GET /v1/dns/provisioning-runs/{run_id}

curl https://api.tenantcore.io/v1/dns/provisioning-runs/RUN_UUID \
  -H "Authorization: Bearer tc_live_your_key"

The run_id must belong to the authenticated TenantCore account. A run from another account is returned as not found. Possible run states include:

queued
running
action_required
completed
failed

Job responses expose customer-actionable state only. Internal worker leases, account UUIDs, notification IDs, raw provider errors, and internal metadata are not returned by the public API.

List provisioning runs

GET /v1/dns/provisioning-runs?active_only=false&limit=20

active_only=true limits the result to queued/running/action-required work. limit may be from 1 to 100.

Retry a provisioning job

After resolving the condition reported by an action_required or waiting job, queue it for another attempt:

POST /v1/dns/provisioning-jobs/{job_id}/retry

curl -X POST \
  https://api.tenantcore.io/v1/dns/provisioning-jobs/JOB_UUID/retry \
  -H "Authorization: Bearer tc_live_your_key" \
  -H "Idempotency-Key: retry-dns-job-001"

The job must belong to a provisioning run owned by the authenticated TenantCore account. TenantCore does not accept a tenant ID, domain name, or provider account in the retry request.

Common errors

Status	Code	Meaning
`402`	entitlement error	Automatic DNS is not available to the current entitlement
`404`	`domain_not_found`	`domain_id` is not an owned TenantCore domain
`404`	`provisioning_run_not_found`	Run does not belong to this account
`404`	`provisioning_job_not_found`	Job does not belong to this account
`409`	`domain_provisioning_already_active`	An automatic run is already active for the domain
`409`	provider/plan conflict	Provider connection or DNS conflict requires attention
`429`	`rate_limit_exceeded`	API quota reached; obey `Retry-After`

See Errors for the common public API error envelope and request IDs.

Overview

Authentication

Endpoints

Overview

Get stored DNS state

Build a live DNS plan

Check automatic-DNS readiness

Start automatic provisioning

Get a provisioning run

List provisioning runs

Retry a provisioning job

Common errors

​Overview

​Get stored DNS state

​Build a live DNS plan

​Check automatic-DNS readiness

​Start automatic provisioning

​Get a provisioning run

​List provisioning runs

​Retry a provisioning job

​Common errors

Overview

Get stored DNS state

Build a live DNS plan

Check automatic-DNS readiness

Start automatic provisioning

Get a provisioning run

List provisioning runs

Retry a provisioning job

Common errors