Domains

Domains are verified host bindings for a publication. A verified host resolves to its active publication; pending challenges do not reserve the host.

Authentication

Management routes require a bearer token and the listed publication capability. User and delegate principals also need an active publication membership; trusted internal principals use their service-wide scope. /domain/resolve is public. Use domain_id or verification_id when available; otherwise a management request needs a publication selector and host.

Routes

Route	Methods	Authorization	Required input	Optional input and behavior	Success result
/domain/list	GET, POST	domain.list	Publication selector	Pagination	Verified domains and pending challenges.
/domain/get	POST	domain.list	domain_id, verification_id, or publication selector plus host	—	domain.
/domain/save	POST	domain.save	Publication selector, host	verification_method	Verification instructions.
/domain/verify	POST	domain.verify	verification_id, or publication selector plus host	—	Verified or pending domain.
/domain/delete	POST	domain.delete	domain_id, verification_id, or publication selector plus host	—	Deleted identifier.
/domain/resolve	GET, POST	None	host	—	public_domain.

Save a verification challenge

Field	Required	Type	Description
publication_id / publication_slug	Yes	UUID / String	Selects the publication.
host	Yes	DNS host name	Host to bind. URLs, ports, paths, wildcards, and IP addresses are invalid.
verification_method	No	http or dns	Defaults to http.

curl -sS https://api.blog.service.m7.org/v1/domain/save \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"publication_slug":"engineering-notes","host":"notes.example.com","verification_method":"dns"}'

The response's domain contains a pending verification object. For DNS, publish the supplied TXT record_name and record_value. For HTTP, return the supplied response_body at the supplied HTTPS url with a 200 response. Hosts are normalized to lowercase with a trailing dot removed. A pending token expires in seven days; save the host again to issue a replacement.

{
  "domain": {
    "domain_id": null,
    "verification_id": "VERIFICATION_UUID",
    "host": "notes.example.com",
    "verified": false,
    "verification_method": "dns",
    "verification_status": "pending",
    "verification": {
      "method": "dns",
      "record_name": "_m7-domain-verification.notes.example.com",
      "record_type": "TXT",
      "record_value": "m7-domain-verification=VERIFICATION_TOKEN"
    }
  }
}

Verify, delete, and resolve

Call /domain/verify with the returned verification_id after publishing the challenge. A missing challenge returns a successful verified: false result; a matching challenge returns verified: true and a domain_id. If the host is already bound to another publication, save or verification returns 409.

Delete a verified binding with domain_id, or cancel a pending challenge with verification_id. Removing a verified domain immediately prevents public resolution.

{ "host": "notes.example.com" }

/domain/resolve returns the verified host's public publication identity:

{
  "public_domain": {
    "host": "notes.example.com",
    "publication_id": "PUBLICATION_UUID",
    "publication_slug": "engineering-notes",
    "publication_name": "Engineering Notes"
  }
}

Only a verified host for an active, unarchived publication resolves. Use the returned publication selector with public read routes.