# 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.
## Who is asking

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

| Caller | Token | Judged by |
|---|---|---|
| An anonymous visitor, such as a public website reading your pages | None | `public` |
| A signed-in user of your account | Issued to that user | `authenticated` |
| An application calling the API as itself, with no user | Issued to the application (client credentials) | `public` |

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

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

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

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

| Permission | Allows |
|---|---|
| `read` | Reading the page and its sections |
| `write` | Editing the page: adding, editing, moving and removing sections |
| `publish` | `publishPage` and `unpublishPage` |
| `updatePermissions` | `updatePagePermissions` |

**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:

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

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

```graphql
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.
## Make a page public

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

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

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

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

```bash
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.
## Applications

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](/docs/users/authentication) for the difference.
---

Previous: [Page Editor](/docs/pages/editor) · Next: [Users overview](/docs/users/overview)