Website domains

Change what a website domain serves

Hands one of your hostnames between Commune's two website origins, or takes it back. Needs settings: write, and is a write.

mode is the only property this changes and the only one it accepts. app is the Commune newsletter page, which is the default every hostname starts on and is where readers sign in, chat and highlight. site is your own pages, built through Creator websites, served from an origin that never carries a Commune session.

One host can carry a session or run your JavaScript, never both. That is why this is a mode rather than two features on one hostname, and why switching to site makes Commune clear the cookies and storage it left on that origin: once your own code runs there, anything Commune kept would be readable by it. Switching back clears what your pages left, for the mirror image of the same reason.

A newsletter holds at most one hostname in each mode. Asking for a mode another of your hostnames already holds answers 409; free it first.

What this does not do. Nothing is reprovisioned: the certificate, the records proving you own the hostname and the target your DNS points at are all untouched, because what changes is which Commune origin answers rather than who owns the name. Adding a hostname and proving ownership of it are not operations here at all.

Publishes no event.

patch/domains/{domain}

Request

  • Base URL: https://api.usecommune.com
  • URL: https://api.usecommune.com/domains/{domain}
  • Auth: one of:
    • HTTP bearer
    • OAuth 2 (authorization code, authorization URL https://usecommune.com/api/oauth/authorize, token URL https://usecommune.com/api/oauth/token, scopes: settings:write)

Headers

Idempotency-Keystring required

A value of your choosing naming the change this request is making.

Send the same value again to retry the same request. Commune replays the answer the first attempt gave instead of making the change twice, and marks the replay with an Idempotent-Replay: true response header. Send a different value for a different change: a key reused for a request that differs in any way answers 409, because replaying an answer to a question you did not ask is a wrong answer you could not detect.

A UUID per change is the usual choice. Remembered for 24 hours, per credential, so two credentials choosing the same value never see each other's answers.

Required, not optional.

Request body

mode'app' | 'site' required

What a hostname serves.

app is the Commune newsletter page, with sessions: readers sign in, chat and highlight there, and it is the mode every hostname starts on. site is the creator's own pages, served from an origin that never carries a Commune session.

One host can carry a session or run creator JavaScript, never both, because the origin is the only security boundary a browser has: code running on an origin that holds a session can call Commune with the visitor's cookie. So a hostname is one or the other, and a newsletter holds at most one of each.

Response

The domain as it stands. mode is what you asked for, whether or not it had to change: asking for the mode a hostname is already on succeeds and alters nothing, which is the answer a retry deserves.

object'domain' required

Always domain.

idstring uuid required

Stable identifier.

domainstring required

The hostname, unique across Commune.

mode'app' | 'site' required

What a hostname serves.

app is the Commune newsletter page, with sessions: readers sign in, chat and highlight there, and it is the mode every hostname starts on. site is the creator's own pages, served from an origin that never carries a Commune session.

One host can carry a session or run creator JavaScript, never both, because the origin is the only security boundary a browser has: code running on an origin that holds a session can call Commune with the visitor's cookie. So a hostname is one or the other, and a newsletter holds at most one of each.

verification_status'pending' | 'active' | 'failed' required

Whether ownership of the domain was proved and a certificate issued. active does not by itself mean the site is reachable, see routing_ok.

ssl_statusstring nullable

Where the certificate stands, as reported by the provider that issues it. Free text rather than an enum, because the vocabulary is the provider's and Commune passes it through.

dns_targetstring nullable

What the creator must point the hostname at.

verification_errorstring nullable

Why verification last failed. Null when it has not failed.

routing_okboolean nullable

Whether the domain actually resolves to Commune, from an end to end request rather than from certificate state. Null before the first probe. This is the field that catches a domain whose certificate is fine but whose DNS points somewhere else.

routing_checked_atstring date-time nullable

When that probe last ran.

verified_atstring date-time nullable

When ownership was first proved. Null if it never was.

last_checked_atstring date-time nullable

When Commune last reconciled the domain with its provider.

created_atstring date-time required

When the domain was added.

Example response

{
  "newsletter": {
    "object": "newsletter",
    "id": "9a4c1c6e-0f2b-4f47-9d3f-6d1b1a2c3d4e"
  },
  "domain": "blog.example.org",
  "verification_records": [
    {
      "type": "CNAME",
      "name": "mail._domainkey.example.org"
    }
  ]
}

Changes

No recorded changes to this operation across all 1 revision of this API.