Publishing and access

Who can read or change a page comes down to two things: who is asking, and the page's permissions. For anonymous readers there is a third: whether the page is published.

This page explains all three, and ends with how to make a page public.

Every request comes from one of three kinds of caller, and the access token decides which:

An application calling as itself sees what an anonymous visitor sees, because nobody has signed in. See Applications below for how to give one more.

Whoever you are, permissions.mine on a page tells you what you can do with it:

query {  page(ref: { slug: "/blog/hello" }) {    permissions {      mine {        read        write        publish        updatePermissions      }    }  }}

A page carries two sets of permissions, public and authenticated, each with four flags:

A new page is private to your account. It is created with every public permission off and every authenticated permission on: any signed-in user of your account can read, edit, publish and re-permission it, and nobody else can do anything.

Every page has its own permissions, and changing one page's permissions changes only that page. To control a whole part of your content at once, such as everything under /blog, use a permission rule in the console. A rule matches a path pattern like /blog/** and can grant or cap access for every page that matches, including pages that already exist, whatever each page's own permissions say.

updatePagePermissions changes only the flags you send, and leaves the rest as they are:

mutation {  updatePagePermissions(    page: { slug: "/blog/hello" }    permissions: { authenticated: { write: false } }  ) {    permissions {      authenticated {        read        write      }    }  }}

A page is a draft until it is published. Publishing needs the publish permission:

mutation {  publishPage(ref: { slug: "/blog/hello" }) {    metadata {      published      publishedAt    }  }}

unpublishPage takes it back: published becomes false and publishedAt is cleared.

Publishing is what anonymous readers wait for. An anonymous visitor, or an application calling as itself, can read a page only when it is published and its public.read is on. Either one alone is not enough.

Signed-in users are not held back by it. Anyone with authenticated.read can read a draft, which is how your team reviews a page before it goes out.

Edits to a published page are live straight away. There is no separate draft of a published page: an edit to one of its sections changes what readers see at once. To prepare a large change out of sight, unpublish the page first, or write the new version as a new page.

Two steps: let the public read it, then publish it.

mutation {  updatePagePermissions(    page: { slug: "/blog/hello" }    permissions: { public: { read: true } }  ) {    id  }}

mutation {  publishPage(ref: { slug: "/blog/hello" }) {    id  }}

Now anyone can read it, with no access token at all:

curl https://graph.[username].mountain-labs.io \  -H 'Content-Type: application/json' \  -d '{"query": "{ page(ref: { slug: \"/blog/hello\" }) { title } }"}'

Send anonymous requests to your own endpoint. With no token, your endpoint is what tells the API whose pages you mean.

An application that calls the API as itself, such as a build step or a backend service, has exactly the permissions an anonymous visitor has: a page's public permissions, and for reading, only once the page is published. With the defaults, that means it can read published, public pages and cannot write anything.

To let an application do more, grant it access to the pages it needs with a permission rule in the console. A rule can, for example, let one application read and write everything under /docs, drafts included, without opening those pages to anyone else.

An application acting for a signed-in user is judged as that user, not as itself. See Authentication for the difference.