From 1ff660d7d664df464a5aba65d38a060dfc5ed20f Mon Sep 17 00:00:00 2001
From: Marion Schleifer <marion@hasura.io>
Date: Mon, 29 Jun 2020 14:50:06 +0200
Subject: [PATCH] docs: clarify unauthenticated access configuration (close
 #2528) (#5217)

---
 .../manual/auth/authentication/index.rst      |  2 +-
 .../authentication/unauthenticated-access.rst | 61 ++++++++++---------
 2 files changed, 33 insertions(+), 30 deletions(-)

diff --git a/docs/graphql/manual/auth/authentication/index.rst b/docs/graphql/manual/auth/authentication/index.rst
index 18e15c6ec43..17d1dd92701 100644
--- a/docs/graphql/manual/auth/authentication/index.rst
+++ b/docs/graphql/manual/auth/authentication/index.rst
@@ -61,4 +61,4 @@ Here's how a GraphQL query is processed in JWT mode:
 
   Using webhooks <webhook>
   Using JWT <jwt>
-  Unauthenticated access <unauthenticated-access>
+  Unauthenticated / Public access <unauthenticated-access>
diff --git a/docs/graphql/manual/auth/authentication/unauthenticated-access.rst b/docs/graphql/manual/auth/authentication/unauthenticated-access.rst
index e4660af6322..ecddd886d46 100644
--- a/docs/graphql/manual/auth/authentication/unauthenticated-access.rst
+++ b/docs/graphql/manual/auth/authentication/unauthenticated-access.rst
@@ -1,48 +1,51 @@
 .. meta::
-   :description: Manage unauthenticated access in Hasura
-   :keywords: hasura, docs, authentication, auth, unauthenticated access
+   :description: Manage unauthenticated / public access in Hasura
+   :keywords: hasura, docs, authentication, auth, unauthenticated access, public access
 
 .. _unauthenticated_access:
 
-Unauthenticated access
-======================
+Unauthenticated / Public access
+===============================
 
 .. contents:: Table of contents
   :backlinks: none
-  :depth: 1
+  :depth: 2
   :local:
 
-Use case
---------
+Introduction
+------------
 
 It is a common requirement to have requests which are accessible to all users without the need for any authentication
 (logging in). For example, to display a public feed of events.
 
-You can configure Hasura GraphQL engine to allow access to unauthenticated users by defining a specific role
-which will be set for all unauthenticated requests.
+Once you have configured authentication, by default Hasura GraphQL engine will reject any unauthenticated request it
+receives. 
 
-Configuring unauthenticated access
-----------------------------------
+You can configure Hasura GraphQL engine to allow access to unauthenticated users by defining a specific role
+which will be set for all unauthenticated requests. Once an unauthenticated role is configured, unaunthenticated requests will 
+not be rejected and instead the request will be made with the configured role.
+
+This role can then be used to define the permissions for unauthenticated users as described in :ref:`authorization`.
+A guide on setting up unauthenticated user permissions can be found :ref:`here <anonymous_users_example>`.
+
+Configuring unauthenticated / public access
+-------------------------------------------
+
+Depending on your auth setup an unauthenticated role can be configured as follows:
+
+Webhooks
+^^^^^^^^
+
+For :ref:`webhook authentication <auth_webhooks>`, an unauthenticated request is any request for which the webhook returns a ``401 Unauthorized`` response.
+
+For unauthenticated access, you can return a ``200`` status response with your defined unauthenticated role, e.g: ``{ "x-hasura-role": "<anonymous-role>" }``.
+
+JWT
+^^^
+
+For :ref:`JWT authentication <auth_jwt>`, an unauthenticated request is any request which does not contain a JWT token.
 
 You can use the env variable ``HASURA_GRAPHQL_UNAUTHORIZED_ROLE`` or ``--unauthorized-role`` flag to set a role
 for unauthenticated (non-logged in) users. See :ref:`server_flag_reference` for more details
 on setting this flag/env var.
 
-This role can then be used to define the permissions for unauthenticated users as described in :ref:`authorization`.
-A guide on setting up unauthenticated user permissions can be found :ref:`here <anonymous_users_example>`.
-
-How it works
-------------
-
-Once you have configured authentication, by default Hasura GraphQL engine will reject any unauthenticated request it
-receives.
-
-Based on your authentication setup, an unauthenticated request is any request:
-
-- for which the webhook returns a ``401 Unauthorized`` response in case of :ref:`webhook authentication <auth_webhooks>`.
-- which does not contain a JWT token in case of :ref:`JWT authentication <auth_jwt>`.
-
-Once an unauthenticated role is configured, unaunthenticated requests will not be rejected and instead the request will
-be made with the configured role.
-
-