Headless or coupled

Every site has a Mode on the Sites screen, under Runtime in the sidebar. Only a master can change it.

A Phoenix Only site answers an API request with status 403 and the code api_access_denied, and it sends no CORS headers. An API Only site answers a web visit with a 403 page that reads Web Access Not Allowed.

The host's router ends with one catch-all route. It sends every path that no other route claims to a single LiveView, MishkaCmsWeb.RuntimeLive. For each request, the CMS:

1. finds the site from the host name of the request;
2. finds the page whose path matches the address and the site's language settings;
3. renders the page's compiled module inside its layout.

Pages, layouts, components, error pages, stylesheets and JS hooks are rows in the database. Publishing a change compiles it while the app runs, so a coupled site changes without a deploy. The sign-in pages are runtime pages as well. How a page reaches visitors follows one page from the editor to the browser.

The JSON:API lives under /api/json. Its route families are:

• The site. Each request is scoped to the site its Host header names. An unknown host answers 404 with the code domain_not_found, and a switched-off site answers 503 with website_unavailable. A master calling the master site's address can send x-no-tenant: true to work across sites.
• Signing in. POST /api/json/v1/auth/user/sign-in returns a token as token in the response's meta. Send it as Authorization: Bearer <token> on later requests.
• Permissions. Admin routes check names that start with admin:api:. A name such as admin:dashboard:* opens nothing here. See How permissions work.
• Browsers on other origins. The CMS sends CORS headers when the request's origin has the site's own host, the site's Frontend Domain, or a host listed under Allowed Origins. It compares hosts and ignores ports.
• The spec. /api/json/open_api and /api/json/swaggerui list every route, filter and field. They open for an account that holds anything under admin:api.
• Maintenance. While a site is offline, its API answers only API admins, masters who hold an admin:api: name included. Sign-in stays open, so they can still get a token.

A team runs its marketing site as its own app at app.example.com and keeps the posts in Mishka CMS at cms.example.com.

1. A master adds a site with the host cms.example.com on the Sites screen, sets Mode to API Only and Frontend Domain to app.example.com. To allow another origin, such as a staging copy, click Add Origin under Allowed Origins.
2. The master sets the Blog extension up on that site with the Site list on the blog dashboard, then writes the posts and picks that site in each post's Site field.
3. The app asks for the published posts:

curl https://cms.example.com/api/json/v1/user/mishka-blog/post/published \
  -H "Accept: application/vnd.api+json"

The Host header names cms.example.com, so the request runs against that site. A browser on app.example.com gets the CORS headers it needs, and an unlisted origin gets none.

• Read content over the JSON:API: the requests and filters, step by step.
• Add a site and its domain: where a site's host comes from.
• Sites, masters and global records: why a request belongs to one site.
• How permissions work: the admin:api: names.