Merge branch 'master' into webdeb-remove-dublicate-section

.circleci/config.yml

@@ -1,9 +1,7 @@
 # anchor refs to be used elsewhere
 refs:
   constants:
-  # TODO upload to hasura docker hub:
+  - &server_builder_image hasura/graphql-engine-server-builder:2020-08-26
-  # - &server_builder_image hasura/graphql-engine-server-builder:2020-01-14
-  - &server_builder_image jberryman/graphql-engine-server-builder-8.10:2020-04-29
   skip_job_on_ciignore: &skip_job_on_ciignore
     run:
       name: checking if job should be terminated or not
@@ -22,7 +20,7 @@ refs:
         if [ -z "$CIRCLE_PR_NUMBER" ]; then
           echo "Not a PR build, continuing test" && exit 0
         fi
-        echo "Compare refs: ${CIRCLE_COMPARE_URL##http*/}" 
+        echo "Compare refs: ${CIRCLE_COMPARE_URL##http*/}"
         if git diff --quiet "${CIRCLE_COMPARE_URL##http*/}" -- server; then
           echo "No server changes present, skipping test"
           circleci-agent step halt
@@ -165,10 +163,10 @@ jobs:
     - checkout
     - restore_cache:
         keys:
-        - cabal-store-v2-{{ checksum "server/cabal.project" }}-{{ checksum "server/graphql-engine.cabal" }}-{{ checksum "server/cabal.project.freeze" }}
+        - cabal-store-v3-{{ checksum "server/cabal.project" }}-{{ checksum "server/graphql-engine.cabal" }}-{{ checksum "server/cabal.project.freeze" }}
-        - cabal-store-v2-{{ checksum "server/cabal.project" }}-{{ checksum "server/graphql-engine.cabal" }}-
+        - cabal-store-v3-{{ checksum "server/cabal.project" }}-{{ checksum "server/graphql-engine.cabal" }}-
-        - cabal-store-v2-{{ checksum "server/cabal.project" }}-
+        - cabal-store-v3-{{ checksum "server/cabal.project" }}-
-        - cabal-store-v2-
+        - cabal-store-v3-
     - run:
         name: Install latest postgresql client tools
         command: |
@@ -187,7 +185,7 @@ jobs:
             make enable_coverage=true ci-build
           fi
     - save_cache:
-        key: cabal-store-v2-{{ checksum "server/cabal.project" }}-{{ checksum "server/graphql-engine.cabal" }}-{{ checksum "server/cabal.project.freeze" }}
+        key: cabal-store-v3-{{ checksum "server/cabal.project" }}-{{ checksum "server/graphql-engine.cabal" }}-{{ checksum "server/cabal.project.freeze" }}
         paths:
         - ~/.cabal/packages
         - ~/.cabal/store
@@ -416,7 +414,7 @@ jobs:
         root: /build
         paths:
           - _cli_output
-  
+
   test_and_build_cli_migrations:
     docker:
     - image: hasura/graphql-engine-cli-migrations-builder:20200415

.circleci/server-builder.dockerfile

@@ -1,8 +1,6 @@
 # Don't update this without updating the
 # packager imager of graphql-engine
-FROM phadej/ghc:8.10.1-stretch
+FROM haskell:8.10.2-stretch
-# TODO https://github.com/haskell/docker-haskell/issues/17
-#FROM haskell:8.10.1
 
 ARG docker_ver="17.09.0-ce"
 ARG postgres_ver="12"
@@ -14,7 +12,10 @@ RUN apt-get -y update \
     && echo "deb http://apt.postgresql.org/pub/repos/apt/ stretch-pgdg main" > /etc/apt/sources.list.d/pgdg.list \
     && curl -s https://www.postgresql.org/media/keys/ACCC4CF8.asc | apt-key add - \
     && apt-get -y update \
-    && apt-get install -y g++ gcc libc6-dev libpq-dev libffi-dev libgmp-dev make xz-utils zlib1g-dev git gnupg upx netcat python3 python3-pip postgresql-client-${postgres_ver} postgresql-client-common \
+    && apt-get install -y \
+         g++ gcc git gnupg libc6-dev libffi-dev libgmp-dev libkrb5-dev \
+         libpq-dev libssl-dev make netcat postgresql-client-${postgres_ver} \
+         postgresql-client-common python3 python3-pip upx xz-utils zlib1g-dev \
     && curl -sL https://deb.nodesource.com/setup_${node_ver} | bash - \
     && apt-get install -y nodejs \
     && curl -Lo /tmp/docker-${docker_ver}.tgz https://download.docker.com/linux/static/stable/x86_64/docker-${docker_ver}.tgz \

.circleci/test-server.sh

@@ -383,6 +383,51 @@ kill_hge_servers
 
 unset HASURA_GRAPHQL_JWT_SECRET
 
+# test JWT with Claims map
+echo -e "\n$(time_elapsed): <########## TEST GRAPHQL-ENGINE WITH ADMIN SECRET AND JWT (with claims_map and values are json path) #####################################>\n"
+TEST_TYPE="jwt-claims-map-with-json-path-values"
+
+export HASURA_GRAPHQL_JWT_SECRET="$(jq -n --arg key "$(cat $OUTPUT_FOLDER/ssl/jwt_public.key)" '{ type: "RS512", key: $key , claims_map: {"x-hasura-user-id": {"path":"$.['"'"'https://myapp.com/jwt/claims'"'"'].user.id"}, "x-hasura-allowed-roles": {"path":"$.['"'"'https://myapp.com/jwt/claims'"'"'].role.allowed"}, "x-hasura-default-role": {"path":"$.['"'"'https://myapp.com/jwt/claims'"'"'].role.default"}}}')"
+
+run_hge_with_args serve
+wait_for_port 8080
+
+pytest -n 1 -vv --hge-urls "$HGE_URL" --pg-urls "$HASURA_GRAPHQL_DATABASE_URL" --hge-key="$HASURA_GRAPHQL_ADMIN_SECRET" --hge-jwt-key-file="$OUTPUT_FOLDER/ssl/jwt_private.key" --hge-jwt-conf="$HASURA_GRAPHQL_JWT_SECRET" test_jwt_claims_map.py::TestJWTClaimsMapBasic
+
+kill_hge_servers
+
+unset HASURA_GRAPHQL_JWT_SECRET
+
+echo -e "\n$(time_elapsed): <########## TEST GRAPHQL-ENGINE WITH ADMIN SECRET AND JWT (with claims_map and values are json path with default values set) #####################################>\n"
+TEST_TYPE="jwt-claims-map-with-json-path-values-with-default-values"
+
+export HASURA_GRAPHQL_JWT_SECRET="$(jq -n --arg key "$(cat $OUTPUT_FOLDER/ssl/jwt_public.key)" '{ type: "RS512", key: $key , claims_map: {"x-hasura-user-id": {"path":"$.['"'"'https://myapp.com/jwt/claims'"'"'].user.id", "default":"1"}, "x-hasura-allowed-roles": {"path":"$.['"'"'https://myapp.com/jwt/claims'"'"'].role.allowed", "default":["user","editor"]}, "x-hasura-default-role": {"path":"$.['"'"'https://myapp.com/jwt/claims'"'"'].role.default","default":"user"}}}')"
+
+run_hge_with_args serve
+wait_for_port 8080
+
+pytest -n 1 -vv --hge-urls "$HGE_URL" --pg-urls "$HASURA_GRAPHQL_DATABASE_URL" --hge-key="$HASURA_GRAPHQL_ADMIN_SECRET" --hge-jwt-key-file="$OUTPUT_FOLDER/ssl/jwt_private.key" --hge-jwt-conf="$HASURA_GRAPHQL_JWT_SECRET" test_jwt_claims_map.py::TestJWTClaimsMapBasic
+
+kill_hge_servers
+
+unset HASURA_GRAPHQL_JWT_SECRET
+
+
+echo -e "\n$(time_elapsed): <########## TEST GRAPHQL-ENGINE WITH ADMIN SECRET AND JWT (with claims_map and values are literal values) #####################################>\n"
+TEST_TYPE="jwt-claims-map-with-literal-values"
+
+export HASURA_GRAPHQL_JWT_SECRET="$(jq -n --arg key "$(cat $OUTPUT_FOLDER/ssl/jwt_public.key)" '{ type: "RS512", key: $key , claims_map: {"x-hasura-user-id": {"path":"$.['"'"'https://myapp.com/jwt/claims'"'"'].user.id"}, "x-hasura-allowed-roles": ["user","editor"], "x-hasura-default-role": "user","x-hasura-custom-header":"custom-value"}}')"
+
+run_hge_with_args serve
+wait_for_port 8080
+
+pytest -n 1 -vv --hge-urls "$HGE_URL" --pg-urls "$HASURA_GRAPHQL_DATABASE_URL" --hge-key="$HASURA_GRAPHQL_ADMIN_SECRET" --hge-jwt-key-file="$OUTPUT_FOLDER/ssl/jwt_private.key" --hge-jwt-conf="$HASURA_GRAPHQL_JWT_SECRET" test_jwt_claims_map.py::TestJWTClaimsMapWithStaticHasuraClaimsMapValues
+
+kill_hge_servers
+
+unset HASURA_GRAPHQL_JWT_SECRET
+
+
 # test with CORS modes
 
 echo -e "\n$(time_elapsed): <########## TEST GRAPHQL-ENGINE WITH CORS DOMAINS ########>\n"

CHANGELOG.md

@@ -2,6 +2,41 @@
 
 ## Next release
 
+### Server - Support for mapping session variables to default JWT claims
+
+Some auth providers do not let users add custom claims in JWT. In such cases, the server can take a JWT configuration option called `claims_map` to specify a mapping of Hasura session variables to values in existing claims via JSONPath or literal values.
+
+Example:-
+
+Consider the following JWT claim:
+
+```
+  {
+    "sub": "1234567890",
+    "name": "John Doe",
+    "admin": true,
+    "iat": 1516239022,
+    "user": {
+      "id": "ujdh739kd",
+      "appRoles": ["user", "editor"]
+    }
+  }
+```
+
+The corresponding JWT config can be:
+
+```
+  {
+    "type":"RS512",
+    "key": "<The public Key>",
+    "claims_map": {
+      "x-hasura-allowed-roles": {"path":"$.user.appRoles"},
+      "x-hasura-default-role": {"path":"$.user.appRoles[0]","default":"user"},
+      "x-hasura-user-id": {"path":"$.user.id"}
+    }
+  }
+```
+
 ### Breaking changes
 
 This release contains the [PDV refactor (#4111)](https://github.com/hasura/graphql-engine/pull/4111), a significant rewrite of the internals of the server, which did include some breaking changes:
@@ -11,7 +46,6 @@ This release contains the [PDV refactor (#4111)](https://github.com/hasura/graph
   - if a query selects table `bar` through table `foo` via a relationship, the required permissions headers will be the union of the required headers of table `foo` and table `bar` (we used to only check the headers of the root table);
   - if an insert does not have an `on_conflict` clause, it will not require the update permissions headers.
 
-
 ### Bug fixes and improvements
 
 (Add entries here in the order of: server, console, cli, docs, others)
@@ -19,6 +53,7 @@ This release contains the [PDV refactor (#4111)](https://github.com/hasura/graph
 - server: some mutations that cannot be performed will no longer be in the schema (for instance, `delete_by_pk` mutations won't be shown to users that do not have select permissions on all primary keys) (#4111)
 - server: miscellaneous description changes (#4111)
 - server: treat the absence of `backend_only` configuration and `backend_only: false` equally (closing #5059) (#4111)
+- server: allow remote relationships joining `type` column with `[type]` input argument as spec allows this coercion (fixes #5133)
 - console: allow user to cascade Postgres dependencies when dropping Postgres objects (close #5109) (#5248)
 - console: mark inconsistent remote schemas in the UI (close #5093) (#5181)
 - cli: add missing global flags for seeds command (#5565)

community/sample-apps/svelte-apollo/README.md

@@ -1,22 +1,19 @@
 # svelte-graphql-app
 
-A sample [Svelte 3](https://svelte.dev) app to demonstrate usage of GraphQL Queries, Mutations and Subscriptions with [svelte-apollo](https://github.com/timhall/svelte-apollo), Hasura GraphQL engine and Postgres as database. Forked from the standard svelte [template](https://github.com/sveltejs/template)
+A sample [Svelte 3](https://svelte.dev) app to demonstrate usage of GraphQL Queries, Mutations and Subscriptions with [svelte-apollo](https://github.com/timhall/svelte-apollo), Hasura Cloud and Postgres as database. Forked from the standard svelte [template](https://github.com/sveltejs/template)
 
 [![Edit svelte-graphql](https://codesandbox.io/static/img/play-codesandbox.svg)](https://codesandbox.io/s/github/hasura/graphql-engine/tree/master/community/sample-apps/svelte-apollo?fontsize=14)
 
-## Deploy Hasura
+## Create new Hasura Cloud project
 
-- Deploy Postgres and GraphQL Engine on Heroku:
+- Create new Hasura Cloud project with the `Try a free database with Heroku` option.
-  
-  [![Deploy to
-  heroku](https://www.herokucdn.com/deploy/button.svg)](https://heroku.com/deploy?template=https://github.com/hasura/graphql-engine-heroku)
 
-  Please checkout our [docs](https://hasura.io/docs/1.0/graphql/manual/deployment/index.html) for other deployment methods
+  Please check out our [docs](https://hasura.io/docs/cloud/1.0/manual/getting-started/index.html) for the detailed steps.
 
-- Get the Heroku app URL (say `my-app.herokuapp.com`)
+- Get the app URL (something like `https://<my-project-name>.hasura.app`)
 - Create `author` table:
-  
+
-  Open Hasura console: visit https://my-app.herokuapp.com on a browser  
+  Open your Hasura Cloud project's console: visit `https://<my-project-name>.hasura.app` on a browser  
   Navigate to `Data` section in the top nav bar and create a table as follows:
 
   ![Create author table](../gatsby-postgres-graphql/assets/add_table.jpg)
@@ -51,7 +48,7 @@ Install the dependencies...
 npm install
 ```
 
-- Open `src/apollo.js` and configure Hasura's GraphQL Endpoint as follows: 
+- Open `src/apollo.js` and configure Hasura's GraphQL Endpoint as follows:
 
 ```javascript
 
@@ -72,7 +69,7 @@ npm install
   });
 
 ```
-Replace the `uri` argument with your Hasura GraphQL Endpoint for both `wsLink` and `httpLink`
+Replace the `uri` argument with your Hasura GraphQL Endpoint (something like `https://<my-project-name>.hasura.app/v1/graphql`) for both `wsLink` and `httpLink`
 
 Start [Rollup](https://rollupjs.org):
 
@@ -99,4 +96,3 @@ now
 ```
 
 This will deploy the app on Now 2.0 Platform and you have the Svetle app running live :)
-

console/src/components/Services/Data/Schema/Schema.js

@@ -692,7 +692,7 @@ class Schema extends Component {
           className={styles.add_mar_top}
           key={'non-trackable-custom-functions'}
         >
-          <CollapsibleToggle title={heading} isOpen>
+          <CollapsibleToggle title={heading}>
             <div className={`${styles.padd_left_remove} col-xs-12`}>
               {getNonTrackableFuncList()}
             </div>

console/src/components/Services/Data/TableRelationships/RelationshipEditor.js

@@ -112,11 +112,11 @@ class RelationshipEditor extends React.Component {
           <div className={styles.display_flex}>
             {getEditBtn()}
             <b className={styles.textNoNewLine}>{relName}</b>
+            <GqlCompatibilityWarning
+              identifier={relName}
+              className={styles.add_mar_left_small}
+            />
           </div>
-          <GqlCompatibilityWarning
-            identifier={relName}
-            className={styles.add_mar_left_small}
-          />
           <div className={tableStyles.relationshipTopPadding}>
             <p className={styles.textNoNewLine}>{getRelDef(relConfig)}</p>
           </div>

docs/404.rst

@@ -1,5 +1,7 @@
 .. title:: 404 - Page Not Found
 
+:orphan:
+
 404 - Page Not Found
 ---------------------
 

docs/_static/scripts/hdocs.js

@@ -14,8 +14,8 @@ window.hdocs = (function () {
 
       docsearch({
         appId: 'WCBB1VVLRC',
-        apiKey: '298d448cd9d7ed93fbab395658da19e8',
+        apiKey: HDOCS_ALGOLIA_API_KEY,
-        indexName: 'graphql-docs-prod',
+        indexName: HDOCS_ALGOLIA_INDEX,
         inputSelector: '#search_element',
         transformData: hdocs.transformSearchData,
         debug: false

docs/_static/styles/landing.css

@@ -15,13 +15,11 @@
 }
 
 .body_content {
-  font-family: 'Gudea';
   font-size: 15px;
   color: #333;
 }
 
 .small_content {
-  font-family: 'Gudea';
   font-size: 14px;
   color: #333;
 }
@@ -101,6 +99,10 @@
   padding-bottom: 0;
 }
 
+.description {
+  margin-bottom: 20px;
+}
+
 .text_left {
   text-align: left;
 }

docs/_static/styles/main.css

@@ -640,6 +640,10 @@ article ol ol {
   margin: 15px;
 }
 
+.sphinxsidebarwrapper > ul:not(.current) {
+  display: none;
+}
+
 #sidebar {
   background-color: #001934;
   width: 24% !important;

docs/_theme/djangodocs/layout.html

@@ -4,6 +4,16 @@
   {% set is_landing_page = true %}
 {%- endif %}
 
+{%- if pagename.startswith('graphql/core') %}
+  {% set is_core = true %}
+  {% set ALGOLIA_INDEX = 'graphql-docs-prod' %}
+  {% set ALGOLIA_API_KEY = '298d448cd9d7ed93fbab395658da19e8' %}
+{%- elif pagename.startswith('graphql/cloud') %}
+  {% set is_cloud = true %}
+  {% set ALGOLIA_INDEX = 'cloud-docs-prod' %}
+  {% set ALGOLIA_API_KEY = 'cf84f05a225bedb72ce472dada63d29f' %}
+{%- endif %}
+
 {% set css_files = css_files + ['_static/graphiql/graphiql.css', '_static/styles/main.css'] %}
 
 {%- if is_landing_page %}
@@ -105,7 +115,7 @@
                   </a>
                 </li>
                 <li>
-                  <a href='https://hasura.io/docs/1.0/graphql/manual/getting-started/index.html'>
+                  <a href='https://hasura.io/docs/1.0/graphql/core/getting-started/index.html'>
                     <button class="commonBtn navBtnHome">
                       Get Started
                     </button>
@@ -162,7 +172,7 @@
                     </a>
                   </li>
                   <li>
-                    <a class="menuLink" href='https://hasura.io/docs/1.0/graphql/manual/getting-started/index.html'>
+                    <a class="menuLink" href='https://hasura.io/docs/1.0/graphql/core/getting-started/index.html'>
                       <button class='commonBtn navBtnHome'>
                         Get Started
                       </button>
@@ -187,12 +197,12 @@
                 <img src="{{ pathto('_images/layout/close-icon.svg', 1) }}" alt="Close"/>
               </div>
               <div class="tabbarContainerWrapper blueBgColor boderBottom">
-                <a href="" class="tabbarTabActive">
+                <a href="{{ pathto('graphql/core/index.html', 1) }}" {%- if is_core %} class="tabbarTabActive" {%- endif %}>
                   <span>
                     Hasura Core
                   </span>
                 </a>
-                <a href="https://hasura.io/docs/cloud/1.0/manual/index.html">
+                <a href="{{ pathto('graphql/cloud/index.html', 1) }}" {%- if is_cloud %} class="tabbarTabActive" {%- endif %}>
                   <span>
                     Hasura Cloud
                   </span>
@@ -283,7 +293,7 @@
                 <div id="mc_embed_signup">
                   <div class="subscribe-form-content">
                     Stay up to date with product & security news
-                    <a target="_blank" class="newsletter-link" href="https://us13.campaign-archive.com/home/?u=9b63e92a98ecdc99732456b0e&id=f5c4f66bcf" rel="noopener">See past editions</a>
+                    <!-- <a target="_blank" class="newsletter-link" href="https://us13.campaign-archive.com/home/?u=9b63e92a98ecdc99732456b0e&id=f5c4f66bcf" rel="noopener">See past editions</a> -->
                   </div>
                   <form id="mc-embedded-subscribe-form" name="mc-embedded-subscribe-form" class="validate post-subscription-form newsletter-form" target="_blank" rel="noopener" novalidate>
                     <div class="full-width">
@@ -344,6 +354,8 @@
   <script type="text/javascript">
     const HDOCS_BASE_DOMAIN = "{{ BASE_DOMAIN }}";
     const HDOCS_GRAPHIQL_DEFAULT_ENDPOINT = "{{ GRAPHIQL_DEFAULT_ENDPOINT }}";
+    const HDOCS_ALGOLIA_INDEX = "{{ALGOLIA_INDEX}}";
+    const HDOCS_ALGOLIA_API_KEY = "{{ALGOLIA_API_KEY}}";
 
     document.addEventListener('DOMContentLoaded', function () {
       hdocs && hdocs.setup();

docs/_theme/djangodocs/localtoc.html

@@ -1,24 +1,3 @@
 {%- if display_toc %}
-  <!--
-  <div class="header_main_logo inline-block mobile-hide">
-    <a href="https://{{ BASE_DOMAIN }}/" target="_blank" rel="noopener">
-      <div class="img_wrapper inline-block">
-        <img class="responsive logo_img" src="{{ pathto('_images/layout/logo-lite.svg', 1) }}" alt="Hasura Logo Light" />
-      </div>
-    </a>
-    <a class="docs_label" href="{{ pathto('', 1) }}">
-      <div class="inline-block hero"> docs </div>
-    </a>
-    <a class="version_txt">
-      <select value="{{ version }}" onchange="location = this.value;" class="selected" aria-label="Select Version">
-        {%- if version == '1.0' %}
-          <option class="option_val" value="https://{{ BASE_DOMAIN }}/docs/1.0/graphql/manual/index.html" selected="selected">v1.x</option>
-        {%- else -%}
-          <option class="option_val" value="https://{{ BASE_DOMAIN }}/docs/1.0/graphql/manual/index.html">v1.x</option>
-        {% endif %}
-      </select>
-    </a>
-  </div>
-  -->
   {{ toc_full }}
 {%- endif %}

docs/_theme/djangodocs/pages/landing.html

@@ -5,25 +5,23 @@
         <div class="box_head_wrapper">
           <div class="box_head">
             <img src="{{ pathto('_images/landing/graphql.svg', 1) }}" alt="GraphQL engine"/>
-            <h3 class="head_wrapper">1. The Hasura GraphQL engine</h3>
+            <h3 class="head_wrapper">Hasura docs</h3>
-          </div>
-          <div class="view_all_wrapper small_content">
           </div>
         </div>
-        <div class="small_content space_wrapper text_left">
+        <div class="space_wrapper text_left">
-          This guide covers all Hasura GraphQL engine concepts and features.
+          <p class="description">This guide covers all Hasura concepts and features.</p>
-          <br/> <br/>
+          <ul>
-        </div>
+            <li>
-        <div class="sign_in_wrapper space_wrapper">
+              <a class="docs_link" href="{{ pathto('graphql/core/index.html', 1) }}">
-          <div class="get_start">
+                Core docs
-            <img src="{{ pathto('_images/landing/manual.svg', 1) }}" alt="Manual"/>
+              </a>
-          </div>
+            </li>
-          <a href="{{ pathto('graphql/manual/index.html', 1) }}">
+            <li>
-            <div class="docs_link body_content">
+              <a class="docs_link" href="{{ pathto('graphql/cloud/index.html', 1) }}">
-              Open manual
+                Cloud docs
-              <img src="{{ pathto('_images/landing/right-arrow.svg', 1) }}" alt="Right Arrow" />
+              </a>
-            </div>
+            </li>
-          </a>
+          </ul>
         </div>
       </div>
     </div>

docs/graphql/cloud/allow-lists.rst

@@ -0,0 +1,34 @@
+.. meta::
+   :description: Hasura Cloud allow lists
+   :keywords: hasura, docs, cloud, security, allow
+
+.. _allow_lists:
+
+Allow lists
+===========
+
+.. contents:: Table of contents
+  :backlinks: none
+  :depth: 1
+  :local:
+
+Introduction
+------------
+
+You can specify a list of safe operations (GraphQL queries, mutations or subscriptions) for your project. This list restricts your project's GraphQL Engine to execute only queries that are present in the list.
+
+Manage the allow list
+---------------------
+
+The manager view offers inspection, export, or removal of operations in the allow list:
+
+.. thumbnail:: /img/graphql/cloud/security/pro-tabs-allowlist.png
+   :alt: Hasura Cloud Console allow list tab
+
+Quick-create allowed operations
+-------------------------------
+
+This Pro feature lets you add to the allow list with one click from the record of past operations. (With Core, allow lists must be :ref:`managed manually <allow_list>`.)
+
+.. thumbnail:: /img/graphql/cloud/security/allowlist-add-new-op.png
+   :alt: Hasura Cloud Console create new allowed operation

docs/graphql/cloud/api-limits.rst

@@ -0,0 +1,49 @@
+.. meta::
+   :description: Hasura Cloud API limits
+   :keywords: hasura, docs, cloud, security, limits
+
+.. _api_limits:
+
+API limits
+==========
+
+.. contents:: Table of contents
+  :backlinks: none
+  :depth: 1
+  :local:
+
+Introduction
+------------
+
+Limiting the depth and/or rate of API requests can help prevent API performance issues caused by malicious or poorly implemented queries. 
+
+Configuring an API limit
+------------------------
+
+**Rate limits**
+  Restricts number of GraphQL operations per minute. This uses a sliding window approach. This means whenever Hasura Pro receives a request, it will count the rate of that client starting from the current time to last one minute.
+
+**Depth limits**
+  Restricts a GraphQL operation based on its depth, preventing deeply nested queries.
+
+API limits are defined by **role** (anonymous, user) and can restrict request rate, depth, or both. Unique request parameters can include IP address or session variables (*x-hasura-user-id*, *x-hasura-org-id*, etc.)
+
+Manage API limits
+-----------------
+
+API limits can have a *global* or *per role* configuration. If an incoming request does not contain a valid role then the global limit is applied.
+
+.. thumbnail:: /img/graphql/cloud/security/pro-tab-apilimits.png
+   :alt: Hasura Cloud Console api limit tab
+
+.. admonition:: Admin & IntrospectionQuery exemptions
+
+  All API limits are **not** applied for the admin role, and depth limits are **NOT** applied to introspection queries
+
+Quick-create limits
+-------------------
+
+Hasura Cloud lets you add limits with one click from the list of past operations.
+
+.. thumbnail:: /img/graphql/cloud/security/pro-tab-apilimit-config.png
+   :alt: Hasura Cloud Console create new api limit

docs/graphql/cloud/api-reference.rst

@@ -0,0 +1,140 @@
+.. meta::
+   :description: Hasura Cloud API reference
+   :keywords: hasura, cloud, docs, API, API reference
+
+.. _cloud_api_reference:
+
+API Reference
+=============
+
+.. contents:: Table of contents
+  :backlinks: none
+  :depth: 1
+  :local:
+
+Introduction
+------------
+
+Hasura Cloud provides a GraphQL API to interact with the services to create
+and manage your projects.
+
+You can use any GraphQL client and use the API with the right authentication header.
+
+.. note::
+
+   Please note that the API is still in beta and might change before the
+   stable release.
+
+Endpoint
+--------
+
+API endpoint is ``https://data.pro.hasura.io/v1/graphql``.
+
+Authentication
+--------------
+
+Authentication is done using a Personal Access Token that you can create from
+the Hasura Cloud Dashboard. You can find this option under the "Settings" tab.
+
+Once you have the token it can be used with the header:
+``Authorization: pat <token>``.
+
+.. note::
+
+   This token can be used to authenticate against Hasura Cloud APIs and your Hasura Cloud projects.
+   Make sure you keep it secure. The token will be valid until you delete it from the dashboard.
+
+APIs
+----
+
+Each Hasura Cloud project is backed by an API entity called "Tenant", with a
+distinct "Tenant ID" which is different from "Project ID". Each Project is
+associated with a Tenant. In some cases, like Metrics API, the Project ID is
+used instead of Tenant ID.
+
+List of APIs:
+
+.. contents::
+  :backlinks: none
+  :depth: 1
+  :local:
+
+Create a Tenant
+^^^^^^^^^^^^^^^
+
+.. code-block:: graphql
+
+   mutation createProject {
+     createTenant(
+       cloud: "aws"
+       region: "us-east-2"
+       databaseUrl: "postgres://username:password@database-host.com:5432/dbname"
+     ) {
+       id
+       name
+     }
+   }
+
+Get Tenant details
+^^^^^^^^^^^^^^^^^^
+
+.. code-block:: graphql
+
+   query getTenantDetails {
+     tenant_by_pk(
+       id: "7a79cf94-0e53-4520-a560-1b02bf522f08"
+     ) {
+       id
+       slug
+       project {
+         id
+         endpoint
+       }
+     }
+   }
+
+Delete a Tenant
+^^^^^^^^^^^^^^^
+
+.. code-block:: graphql
+
+   mutation deleteTenant {
+     deleteTenant(
+       tenantId: "7a79cf94-0e53-4520-a560-1b02bf522f08"
+     ) {
+       status
+     }
+   }
+
+Get ENV Vars
+^^^^^^^^^^^^
+
+.. code-block:: graphql
+
+   query getTenantENV {
+     getTenantEnv(
+       tenantId: "7a79cf94-0e53-4520-a560-1b02bf522f08"
+     ) {
+       hash
+       envVars
+     }
+   }
+
+Update ENV Vars
+^^^^^^^^^^^^^^^
+
+.. code-block:: graphql
+
+   mutation updateTenantEnv {
+     updateTenantEnv(
+       tenantId: "7a79cf94-0e53-4520-a560-1b02bf522f08"
+       currentHash: "6902a395d70072fbf8d36288f0eacc36c9d82e68"
+       envs: [
+         {key: "HASURA_GRAPHQL_ENABLE_CONSOLE", value: "true"},
+         {key: "ACTIONS_ENDPOINT", value: "https://my-actions-endpoint.com/actions"}
+       ]
+     ) {
+       hash
+       envVars
+     }
+   }

docs/graphql/cloud/getting-started/index.rst

@@ -0,0 +1,93 @@
+.. meta::
+   :description: Hasura Cloud getting started
+   :keywords: hasura, docs, cloud, signup
+
+.. _cloud_getting_started:
+
+Getting Started with Hasura Cloud
+=================================
+
+.. contents:: Table of contents
+  :backlinks: none
+  :depth: 1
+  :local:
+
+Step 1: Create an account
+-------------------------
+
+Navigate to `cloud.hasura.io 
+<https://cloud.hasura.io/login>`__, and create a new Hasura Cloud account.
+
+.. _cloud_connect_db:
+
+Step 2: Connect new/existing database
+-------------------------------------
+
+- To use an existing database, choose ``I have an existing Postgres database``.
+- To create a new database, choose ``Try a free database with Heroku``.
+
+.. thumbnail:: /img/graphql/cloud/getting-started/connect-db.png
+   :alt: Connect new or existing database
+   :width: 591px
+
+Step 2a: Enter database URL (for existing database)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+If you chose ``I have an existing Postgres database`` in :ref:`Step 2 <cloud_connect_db>`, enter a database URL.
+
+.. thumbnail:: /img/graphql/cloud/getting-started/connect-existing-db.png
+   :alt: Enter URL for existing database
+   :width: 556px
+
+Step 3: Create project
+----------------------
+
+Click ``Create Project``.
+
+.. thumbnail:: /img/graphql/cloud/getting-started/create-project-new-db.png
+   :alt: Create project for new database
+   :width: 539px
+   :group: create
+   :class: inline-block
+
+.. thumbnail:: /img/graphql/cloud/getting-started/create-project-existing-db.png
+   :alt: Create project for existing database
+   :width: 552px
+   :group: create
+   :class: inline-block
+
+Next steps
+----------
+
+Once you've created your project, you can get started with building with Hasura or manage your project.
+
+.. contents::
+  :backlinks: none
+  :depth: 1
+  :local:
+
+.. thumbnail:: /img/graphql/cloud/getting-started/project-functionalities.png
+  :alt: Project actions
+  :width: 860px
+
+
+Explore the Hasura console
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Click ``Launch Console`` to open the Hasura console in your browser and :ref:`make your first GraphQL query <first_graphql_query>` or :ref:`set up your first event trigger <first_event_trigger>`.
+
+You can navigate to the ``Pro`` tab to check out the Pro features that Hasura Cloud has set up for you.
+
+.. thumbnail:: /img/graphql/cloud/metrics/pro-tab-overview.png
+   :alt: Hasura Console: Pro tab
+   :width: 1118px
+
+Manage your project
+^^^^^^^^^^^^^^^^^^^
+
+Click the gear icon to :ref:`manage your project <manage_project>` (e.g. add collaborators, env vars or custom domains).
+
+Add an admin secret
+^^^^^^^^^^^^^^^^^^^
+
+:ref:`Add an admin secret <secure_project>` to make sure that your GraphQL endpoint and the Hasura console are not publicly accessible.

docs/graphql/cloud/glossary.rst

@@ -0,0 +1,66 @@
+.. meta::
+   :description: Hasura Cloud glossary
+   :keywords: hasura, docs, cloud, glossary
+
+.. _glossary:
+
+Glossary
+========
+
+.. contents:: Table of contents
+  :backlinks: none
+  :depth: 1
+  :local:
+
+Hasura Cloud Project
+--------------------
+
+A Project is an individual GraphQL API hosted by Hasura Cloud. You
+can create a Project by going to the cloud dashboard and providing
+a PostgreSQL database URL. You can also provision a database on
+cloud platforms like Heroku from the Hasura Cloud Dashboard itself.
+
+Each project is allocated a unique auto-generated name and an ID.
+You can use this name or ID while communicating to Hasura team
+regarding this project. Each project is also assigned a GraphQL API
+endpoint of the format ``https://<project-name>.hasura.app/v1/graphql``.
+
+Editing the Project name and adding custom domains will be available soon.
+
+For example, a project might be called ``usable-cobra-29`` with ID
+``bf0ea856-76a2-42c2-8a91-66ca9b9206e8``.
+
+Hasura Cloud IP
+---------------
+
+A Hasura Cloud IP will be listed on the Hasura Cloud Dashboard for
+each project. Hasura will be connecting to your database from this IP address.
+If your database is not exposed to the internet, you must allow connections 
+from this IP address on your firewall settings
+for Hasura Cloud Project to function properly. Otherwise, Hasura will not 
+be able to connect to your database and the GraphQL API will not be available.
+
+Hasura Collaborator Token
+-------------------------
+
+When you open the Hasura Console on a Cloud Project, you will not be asked to
+enter the admin secret like Hasura Core version. Instead, you will be
+automatically logged into the Console via an OAuth2.0 based authorization flow.
+You will be given the right access based on your permissions for the particular
+Hasura Cloud Project.
+
+After the login process is complete, you'll see a new header called
+``Hasura-Collaborator-Token`` in the "Request Headers" section of GraphiQL. 
+This token is used instead of admin secret to authenticate and authorize
+all the requests made from the Console. The token is only valid for 5mins
+and is refreshed silently by the Console. It is to be used only from Console.
+
+For accessing the API from other clients, use the admin secret or create
+a Personal Access Token.
+
+Hasura Client Name
+------------------
+
+``Hasura-Client-Name`` will be set to ``hasura-console`` by default. It is
+used to identify the client who is making the request in Hasura Pro metrics
+and monitoring tools.

docs/graphql/cloud/hasurapro-cli/index.rst

@@ -0,0 +1,70 @@
+.. meta::
+   :description: Hasura Pro CLI
+   :keywords: hasura, docs, command line interface, cli
+
+.. _hasurapro_cli:
+
+Hasura Pro CLI
+==============
+
+.. contents:: Table of contents
+  :backlinks: none
+  :depth: 1
+  :local:
+
+
+Installing the Hasura Pro CLI
+-----------------------------
+
+Hasura Pro CLI is distributed as a plugin to the :ref:`Hasura Core CLI <hasuracli_manual>`
+
+- Follow the instructions :ref:`here <install_hasura_cli>` to install Hasura Core CLI
+
+- Then execute the following command to install the Hasura Pro CLI plugin:
+
+  .. code-block:: bash
+
+    hasura plugins install pro
+
+- You can verify the installation by executing the ``help`` command:
+
+  .. code-block:: bash
+
+     hasura pro --help
+
+Authentication with the Hasura Pro CLI
+--------------------------------------
+
+All interactions from the CLI to Hasura’s APIs are authenticated using a personal access token generated for your user account.
+
+To set up a token, execute the following command on the CLI:
+
+.. code-block:: bash
+
+   hasura pro login
+
+This command will show a prompt for entering the personal access token.
+
+Head to your `Hasura Cloud account settings <https://cloud.hasura.io>`_ to create a new token. You can name it something like "cli". Note that the token will be shown only once and as soon as you copy the token, paste it in your terminal prompt.
+
+.. admonition:: Keep this token secure!
+
+  This token can be used to authenticate against Hasura Pro APIs and your Hasura Cloud projects. Make sure you keep it secure. This is a one-time operation. The token will be valid until you delete it.
+
+Upgrading the CLI
+-----------------
+
+To upgrade to a newer version, you can use the ``upgrade`` command:
+
+.. code-block:: bash
+
+   hasura plugins upgrade pro
+
+Uninstalling the CLI
+--------------------
+
+To uninstall the CLI, use the ``uninstall`` command:
+
+.. code-block:: bash
+
+   hasura plugins uninstall pro

docs/graphql/cloud/index.rst

@@ -0,0 +1,74 @@
+.. meta::
+   :description: Hasura Cloud documentation
+   :keywords: hasura, docs, manual, graphql engine, cloud, hosted
+
+.. title:: Hasura Cloud Documentation
+
+.. _cloud_docs:
+
+Hasura Cloud Documentation
+==========================
+
+`Hasura Cloud <https://cloud.hasura.io/>`__ offers hosted `GraphQL Engine <https://github.com/hasura/graphql-engine>`__
+projects with extra features for reliability and security. It includes all the :ref:`core features <core_docs>`
+of GraphQL Engine, while taking care of infrastructure concerns, such as the number of instances, cores, memory, concurrent users, high-availability,
+realtime monitoring, caching, tracing, and rate-limiting. It supports both new and existing PostgreSQL databases.
+
+.. container:: toc-list
+
+  .. container:: toc-list-section
+
+    .. container:: toc-list-head
+
+      Basics
+
+    .. container:: toc-list-content
+
+      - :ref:`cloud_getting_started`
+      - :ref:`projects`
+
+  .. container:: toc-list-section
+
+    .. container:: toc-list-head
+
+      Features
+
+    .. container:: toc-list-content
+
+      - :ref:`metrics`
+      - :ref:`api_limits`
+      - :ref:`allow_lists`
+      - :ref:`regression_tests`
+      - :ref:`read_replicas`
+      - :ref:`response_caching`
+      - :ref:`tracing`
+
+  .. container:: toc-list-section
+
+    .. container:: toc-list-head
+
+      Reference
+
+    .. container:: toc-list-content
+
+      - :ref:`cloud_api_reference`
+      - :ref:`glossary`
+      - :ref:`hasurapro_cli`
+
+.. toctree::
+  :maxdepth: 1
+  :titlesonly:
+  :hidden:
+
+  Getting Started <getting-started/index>
+  projects/index
+  metrics/index
+  api-limits
+  allow-lists
+  regression-tests
+  read-replicas
+  response-caching
+  tracing
+  hasurapro-cli/index
+  api-reference
+  glossary

docs/graphql/cloud/metrics/errors.rst

@@ -0,0 +1,23 @@
+.. meta::
+   :description: Hasura Cloud error analysis
+   :keywords: hasura, docs, cloud, reliability, errors
+
+.. _errors:
+
+Errors
+======
+
+.. contents:: Table of contents
+  :backlinks: none
+  :depth: 1
+  :local:
+
+Troubleshoot errors quickly with powerful analytical tools and filters:
+
+.. thumbnail:: /img/graphql/cloud/metrics/pro-tab-errors.png
+   :alt: Hasura Cloud Console errors tab
+
+Drill into a specific operation via the magnifying-glass icon next to the operation summary in the 'Frequent errors' table. You'll be taken to a list of the failed operations, and can choose one to inspect the specific operation content, metadata, and error generated:
+
+.. thumbnail:: /img/graphql/cloud/metrics/inspect-error.png
+   :alt: Hasura Cloud Console inspect a failed operation

docs/graphql/cloud/metrics/index.rst

@@ -0,0 +1,35 @@
+.. meta::
+   :description: Hasura Cloud metrics
+   :keywords: hasura, docs, cloud, metrics
+
+.. _metrics:
+
+Metrics
+=======
+
+.. contents:: Table of contents
+  :backlinks: none
+  :depth: 1
+  :local:
+
+Introduction
+------------
+
+Hasura Cloud projects include Pro features for enhanced reliability and performance
+
+.. thumbnail:: /img/graphql/cloud/metrics/pro-tab-overview.png
+   :alt: Hasura Cloud Console overview tab
+
+Learn more
+----------
+
+.. toctree::
+   :maxdepth: 1
+   :titlesonly:
+
+   overview
+   errors
+   usage
+   operations
+   websockets
+   subscription-workers

docs/graphql/cloud/metrics/operations.rst

@@ -0,0 +1,119 @@
+.. meta::
+   :description: Hasura Cloud operation analysis
+   :keywords: hasura, docs, cloud, reliability, operations
+
+.. _operations:
+
+Operations
+==========
+
+.. contents:: Table of contents
+  :backlinks: none
+  :depth: 1
+  :local:
+
+Terminology
+-----------
+
+**Operation**
+  Any GraphQL (query, mutation, subscription) request made to v1/graphql endpoint of a GraphQL engine instance
+
+**Operation name**
+  (Optional) Any GraphQL request can be labelled with a name by the client making the query. In this example, *getPollOptions* is the operation name:
+
+  .. code-block:: graphql
+
+   query getPollOptions (
+     poll {
+       options {
+         id
+         name
+         description
+       }
+     }
+   }
+
+**Operation ID**
+  A unique, auto-generated hash for each Operation name; can distinguish between different operations executed with the same name
+
+**Operation type**
+  Whether the operation is a query, mutation, or subscription
+
+**Request ID**
+  A unique, auto-generated ID for each request, comes from x-request-id HTTP header
+
+**Websocket ID**
+  A unique ID generated by the server when a websocket connection is established by the client
+
+**Websocket Operation ID**
+  A unique ID generated by the websocket client for each operation it is sending to the server
+
+Operations
+----------
+
+Processed realtime logs of all requests to the GraphQL Engine. View all and inspect individual operations:
+
+.. thumbnail:: /img/graphql/cloud/metrics/pro-tab-operations.png
+   :alt: Hasura Cloud Console list operations
+
+.. thumbnail:: /img/graphql/cloud/metrics/pro-tab-operations-inspect.png
+   :alt: Hasura Cloud Console inspect operation
+
+Filtering operations
+--------------------
+
+Click on the **Filter** header to open the menu of filter options
+
+.. list-table::
+   :header-rows: 1
+
+   * - Filter option
+     - Filter type
+     - Example or options
+   * - Time range
+     - timestamps
+     - last hour, last 6 hours, last 12 hours, last 24 hours, or custom range
+   * - Operation ID
+     - string (text field)
+     - 5284946f4e15aa81bc868316d56aa68f
+   * - Operation Name
+     - string (text field)
+     - getPollOptions
+   * - Request ID
+     - string (text field)
+     - e15f7bj9-3b9f-4152-92a4-e745471514af
+   * - Show only errors
+     - boolean (checkbox field)
+     - true or false (default false)
+   * - Websocket ID
+     - string (text field)
+     - def703fc-851f-48e8-8e5c-cbdead37b2fe
+   * - Websocket Operation ID
+     - string (text field)
+     - 110
+   * - Hide introspection query
+     - boolean (checkbox field)
+     - true or false (default false)
+   * - Operation Type
+     - enum (select field)
+     - query, mutation, subscription, all
+   * - Role
+     - enum (select field)
+     - from *x-hasura-user-role*: no role, admin, user, ...
+   * - Error Code
+     - enum (select field)
+     - no error code, access-denied, depth-limit-exceeded, ...
+   * - Client Name
+     - enum (select field)
+     - no client name, hasura-console, hasura-test-runner, ...
+   * - Transport
+     - enum (select field)
+     - http or ws
+   * - Status
+     - enum (select field)
+     - started or closed
+
+Sorting operations
+------------------
+
+Each column in the **Operations List** can be sorted (ascending or descending) just by clicking on it. Very useful for identifying operations with unusually high execution time or response size!

docs/graphql/cloud/metrics/overview.rst

@@ -0,0 +1,18 @@
+.. meta::
+   :description: Hasura Cloud overview
+   :keywords: hasura, docs, cloud, overview
+
+.. _overview:
+
+Overview
+========
+
+.. contents:: Table of contents
+  :backlinks: none
+  :depth: 1
+  :local:
+
+The Overview displays aggregate stats over the last hour:
+
+.. thumbnail:: /img/graphql/cloud/metrics/pro-tab-overview.png
+   :alt: Hasura Cloud Console overview tab

docs/graphql/cloud/metrics/subscription-workers.rst

@@ -0,0 +1,18 @@
+.. meta::
+   :description: Hasura Cloud subscription workers
+   :keywords: hasura, docs, cloud, reliability, subscriptions
+
+.. _subscription_workers:
+
+Subscription workers
+====================
+
+.. contents:: Table of contents
+  :backlinks: none
+  :depth: 1
+  :local:
+
+Subscription workers offers a subscription-worker-specific version of usage statistics:
+
+.. thumbnail:: /img/graphql/cloud/metrics/pro-tab-subscription-workers.png
+   :alt: Hasura Cloud Console subscription workers tab

docs/graphql/cloud/metrics/usage.rst

@@ -0,0 +1,23 @@
+.. meta::
+   :description: Hasura Cloud usage analysis
+   :keywords: hasura, docs, cloud, reliability, usage
+
+.. _usage:
+
+Usage
+=====
+
+.. contents:: Table of contents
+  :backlinks: none
+  :depth: 1
+  :local:
+
+Learn about usage with aggregate summaries and filtering tools:
+
+.. thumbnail:: /img/graphql/cloud/metrics/pro-tab-usage.png
+   :alt: Hasura Cloud Console usage tab
+
+Drill into an operation via its magnifying-glass icon in the 'Query List' table. You'll be taken to a list of similar operations, and can choose one to inspect for content, metadata, and error generated:
+
+.. thumbnail:: /img/graphql/cloud/metrics/pro-tab-operations-inspect.png
+   :alt: Hasura Cloud Console inspect an operation

docs/graphql/cloud/metrics/websockets.rst

@@ -0,0 +1,18 @@
+.. meta::
+   :description: Hasura Cloud websockets analysis
+   :keywords: hasura, docs, cloud, reliability, websockets
+
+.. _websockets:
+
+Websockets
+==========
+
+.. contents:: Table of contents
+  :backlinks: none
+  :depth: 1
+  :local:
+
+Websockets is a ws-specific version of usage statistics:
+
+.. thumbnail:: /img/graphql/cloud/metrics/pro-tab-websockets.png
+   :alt: Hasura Cloud Console websockets tab

docs/graphql/cloud/projects/create.rst

@@ -0,0 +1,89 @@
+.. meta::
+   :description: Creating projects on Hasura Cloud
+   :keywords: hasura, cloud, docs, start
+
+.. _create_project:
+
+Creating projects
+=================
+
+.. contents:: Table of contents
+  :backlinks: none
+  :depth: 2
+  :local:
+
+Introduction
+------------
+
+You can create a new Hasura Cloud project with either a new Postgres database, or an existing Postgres database with a publicly available IP address.
+
+To begin, navigate to the ``Projects`` page, and click the ``New Project`` link.
+
+.. thumbnail:: /img/graphql/cloud/projects/create-new-project.png
+   :alt: create new project button
+   :width: 400
+
+Creating a project with a new database
+--------------------------------------
+
+Hasura Cloud does not host databases, but does provide integrations with which you can create databases on managed cloud providers like Heroku. Integrations for AWS, GCP, and Azure are coming soon.
+
+To get started, click ``Try with Heroku``, and follow the prompts to authenticate with Heroku. Hasura Cloud will integrate with your Heroku account and manage the initial setup of a dev-tier Postgres instance. You can always upgrade the instance and manage options later through your Heroku account.
+
+.. thumbnail:: /img/graphql/cloud/projects/create-project-heroku.png
+   :alt: create new hosted project
+
+Creating a project with an existing database
+--------------------------------------------
+
+To create a new Hasura Cloud project connected to an existing Postgres database, click ``Enter Database URL``, and enter your database connection string (looks like ``postgres://username:password@hostname:port/dbname``).
+
+.. thumbnail:: /img/graphql/cloud/projects/new-project-hosted.png
+   :alt: create new hosted project
+
+Allowing connections from Hasura Cloud IP
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+For some cloud services, like GCP, you'll need to adjust your Postgres connection settings to allow connections from the Hasura Cloud IP address. You can copy the IP address from either the copy icon in the ``Database Setup`` window, or the ``Hasura Cloud IP`` field on the project's details view. You may also need to disable SSL. Adding custom cert information to a Hasura Cloud instance is not yet available. 
+
+.. thumbnail:: /img/graphql/cloud/projects/existing-db-setup.png
+   :alt: Existing database setup
+   :width: 568px
+
+.. thumbnail:: /img/graphql/cloud/projects/hasura-cloud-ip.png
+   :alt: Hasura Cloud IP field
+   :width: 1200px
+
+.. thumbnail:: /img/graphql/cloud/projects/gcp-postgres-authorized-network.png
+   :alt: whitelist Hasura instance IP in Postgres settings
+   :width: 727px
+
+Connecting to a database not exposed over the internet
+------------------------------------------------------
+
+`Contact us <https://hasura.io/contact-us/>`__ for VPC peering and on-premise solutions.
+
+.. _cloud_postgres_permissions:
+
+Postgres permissions
+--------------------
+
+Hasura Cloud works with **Postgres versions 9.5 and above**.
+
+If you’re running in a controlled environment, you might need to configure
+Hasura Cloud to use a specific Postgres user that your DBA gives you.
+
+Apart from the :ref:`Hasura Core Postgres permissions <postgres_permissions>`,
+Hasura Cloud needs the following extra permissions:
+
+- (required) Read and write access to ``hdb_pro_catalog`` schema.
+
+.. code-block:: sql
+
+   -- execute these statements after executing the ones mentioned in Hasura Core docs
+   -- create the schemas required by the hasura cloud system
+   CREATE SCHEMA IF NOT EXISTS hdb_pro_catalog;
+   
+   -- make the user an owner of system schemas
+   ALTER SCHEMA hdb_pro_catalog OWNER TO hasurauser;
+

docs/graphql/cloud/projects/delete.rst

@@ -0,0 +1,19 @@
+.. meta::
+   :description: Deleting projects on Hasura Cloud
+   :keywords: hasura, docs, delete
+
+.. _delete_project:
+
+Deleting projects
+=================
+
+.. contents:: Table of contents
+  :backlinks: none
+  :depth: 1
+  :local:
+
+You can delete a project with the ``Delete Project`` button at the bottom of the project's details view.
+
+.. thumbnail:: /img/graphql/cloud/projects/projects-delete.png
+   :alt: delete a project
+   :width: 1199px

docs/graphql/cloud/projects/index.rst

@@ -0,0 +1,52 @@
+.. meta::
+   :description: Managing teams in Hasura Cloud
+   :keywords: hasura, docs, cloud, teams
+
+.. _projects:
+
+Projects & teams
+================
+
+.. contents:: Table of contents
+  :backlinks: none
+  :depth: 1
+  :local:
+
+Introduction
+------------
+
+The ``Projects`` page show a list of your projects.
+
+.. thumbnail:: /img/graphql/cloud/projects/projects-list.png
+   :alt: Projects list
+   :width: 1200px
+
+For each project, you can:
+
+- Click the gear icon to :ref:`manage your project <manage_project>`, or
+- Click ``Launch Console`` to open the Hasura console in your browser, and navigate to the ``Pro`` tab to check out the Pro features that Hasura Cloud has set up for you.
+
+.. thumbnail:: /img/graphql/cloud/getting-started/project-actions.png
+   :alt: Project actions
+   :width: 860px
+
+.. thumbnail:: /img/graphql/cloud/metrics/pro-tab-overview.png
+   :alt: Hasura Console: Pro tab
+   :width: 1118px
+
+.. note::
+
+   Please see the :ref:`API reference <cloud_api_reference>` to create and manage Hasura Cloud projects programmatically.
+
+Dig deeper
+----------
+
+.. toctree::
+   :maxdepth: 1
+   :titlesonly:
+
+   Creating projects <create>
+   Managing projects <manage-projects/index>
+   Securing projects <secure>
+   Deleting projects <delete>
+   

docs/graphql/cloud/projects/manage-projects/domains.rst

@@ -0,0 +1,71 @@
+.. meta::
+   :description: Managing domains on Hasura Cloud
+   :keywords: hasura, docs, project, domains
+
+.. _manage_project_domains:
+
+Domains tab
+===========
+
+.. contents:: Table of contents
+  :backlinks: none
+  :depth: 2
+  :local:
+
+Introduction
+------------
+
+In the ``Domains`` tab, you can see the default Hasura domain, and you have the possibility to add custom domains.
+
+Adding a custom domain
+----------------------
+
+You can add a custom domain to your Hasura Cloud project by following the steps below.
+
+Step 1: Navigate to add a custom domain
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+On the ``Domains`` tab, click on the ``New Custom Domain`` button.
+
+.. thumbnail:: /img/graphql/cloud/projects/add-custom-domain.png
+   :alt: Add custom domain
+   :width: 727px
+
+Step 2: Add your custom domain
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Enter your custom domain and click the ``Add`` button.
+
+.. thumbnail:: /img/graphql/cloud/projects/choose-custom-domain.png
+   :alt: Choose custom domain
+   :width: 727px
+
+Step 3: Add the record to your DNS
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+After adding a custom domain, the following window will show up:
+
+.. thumbnail:: /img/graphql/cloud/projects/dns-settings.png
+   :alt: DNS settings
+   :width: 727px
+
+If you haven't already done so, add the default Hasura domain as a ``CNAME`` record to your DNS.
+
+Until this is done, the dashboard will show a notice that the DNS validation is pending. 
+
+.. thumbnail:: /img/graphql/cloud/projects/dns-validation-pending.png
+   :alt: DNS validation pending
+   :width: 727px
+
+.. note::
+
+  Depending on your DNS provider, it might take up to 24 hours for the DNS record to be added.
+
+DNS validated
+-------------
+
+Once the DNS is validated, the dashboard will update the status with the following notice:
+
+.. thumbnail:: /img/graphql/cloud/projects/dns-validated.png
+   :alt: DNS validated
+   :width: 727px

docs/graphql/cloud/projects/manage-projects/env-vars.rst

@@ -0,0 +1,27 @@
+.. meta::
+   :description: Managing env vars on Hasura Cloud
+   :keywords: hasura, docs, project, env vars
+
+.. _manage_project_env_vars:
+
+Env vars tab
+============
+
+.. contents:: Table of contents
+  :backlinks: none
+  :depth: 2
+  :local:
+
+Introduction
+------------
+
+The ``Env vars`` tab allows setting :ref:`Hasura GraphQL Engine env variables <command-flags>` and adding other custom env variables as well.
+
+Adding an env var
+-----------------
+
+Click on the ``New Env Var`` button and either choose an env var from the dropdown or add a custom env var.
+
+.. thumbnail:: /img/graphql/cloud/projects/add-env-var.png
+   :alt: add env var options
+   :width: 1200px

docs/graphql/cloud/projects/manage-projects/general.rst

@@ -0,0 +1,31 @@
+.. meta::
+   :description: Managing projects on Hasura Cloud
+   :keywords: hasura, docs, project, general
+
+.. _manage_project_general:
+
+General tab
+===========
+
+.. contents:: Table of contents
+  :backlinks: none
+  :depth: 2
+  :local:
+
+Introduction
+------------
+
+The ``General`` tab shows the project's general settings. 
+
+General settings
+----------------
+
+- **Name**: Unique auto-generated name for the project
+- **ID**: Unique auto-generated ID for the project
+- **GraphQL API**: GraphQL endpoint for the project
+- **Admin Secret**: Secret for securing the GraphQL endpoint
+- **Owner**: Email of the project owner
+
+.. thumbnail:: /img/graphql/cloud/projects/project-details.png
+   :alt: General tab
+   :width: 1163px

docs/graphql/cloud/projects/manage-projects/index.rst

@@ -0,0 +1,36 @@
+.. meta::
+   :description: Managing projects on Hasura Cloud
+   :keywords: hasura, docs, project
+
+.. _manage_project:
+
+Managing projects
+=================
+
+.. contents:: Table of contents
+  :backlinks: none
+  :depth: 2
+  :local:
+
+Introduction
+------------
+
+To view a project's details, and manage its teams and environment variables, navigate to the ``Projects`` page and click the gear icon on the project.
+
+.. thumbnail:: /img/graphql/cloud/projects/manage-project.png
+   :alt: Manage project
+   :width: 865px
+
+Managing projects
+-----------------
+
+See the below pages for detailed guides on managing projects:
+
+.. toctree::
+   :maxdepth: 1
+   :titlesonly:
+
+   General tab <general>
+   Team tab <team>
+   Env vars tab <env-vars>
+   Domains tab <domains>

docs/graphql/cloud/projects/manage-projects/team.rst

@@ -0,0 +1,46 @@
+.. meta::
+   :description: Managing teams on Hasura Cloud
+   :keywords: hasura, docs, project, team
+
+.. _manage_project_team:
+
+Team tab
+========
+
+.. contents:: Table of contents
+  :backlinks: none
+  :depth: 2
+  :local:
+
+Introduction
+------------
+
+The ``Team`` tab shows the current people with access to the project. 
+
+Add a collaborator
+------------------
+
+Click ``New Collaborator`` to invite a new team member.
+
+.. thumbnail:: /img/graphql/cloud/projects/team-view.png
+   :alt: Team tab
+   :width: 1146px
+
+Team roles
+^^^^^^^^^^
+
+Team members can have different levels of access in the Hasura console.
+
+- **Admin** has complete access to all project tools and configurations.
+- **User** has limited privileges:
+
+  - The ``Execute GraphQL`` permission allows running queries, mutations, and subscriptions.
+  - The ``View Metrics`` permission allows inspecting operation data and the performance dashboard.
+
+.. thumbnail:: /img/graphql/cloud/projects/add-collaborator.png
+   :alt: Add collaborator
+   :width: 437px
+
+.. note::
+
+  Invitations can be accepted or declined via the ``Invitations`` tab of your Hasura Cloud settings.

docs/graphql/cloud/projects/secure.rst

@@ -0,0 +1,59 @@
+.. meta::
+   :description: Securing projects on Hasura Cloud
+   :keywords: hasura, docs, project
+
+.. _secure_project:
+
+Securing projects
+=================
+
+.. contents:: Table of contents
+  :backlinks: none
+  :depth: 2
+  :local:
+
+Introduction
+------------
+
+To make sure that your GraphQL endpoint and the Hasura console are not publicly accessible, you need to configure an admin secret key.
+
+Adding an admin secret
+----------------------
+
+Step 1: Go to settings
+^^^^^^^^^^^^^^^^^^^^^^
+
+On the project overview, click on the settings icon on the top right of the relevant project.
+
+.. thumbnail:: /img/graphql/cloud/projects/secure-settings.png
+   :alt: Go to settings
+   :width: 865px
+
+Step 2: Navigate to env vars
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+On the ``Env vars`` tab, click the button to add a new env var.
+
+.. thumbnail:: /img/graphql/cloud/projects/secure-envvars.png
+   :alt: Navigate to env vars
+   :width: 865px
+
+Step 3: Add an admin secret
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+In the ``Key`` dropdown, choose ``ADMIN_SECRET`` and add the secret in the ``Value`` field. Then click the ``Add`` button.
+
+.. thumbnail:: /img/graphql/cloud/projects/secure-add-envvar.png
+   :alt: Navigate to env vars
+   :width: 865px
+
+Accessing Hasura
+----------------
+
+After setting an admin secret, when you launch the console from the Hasura Cloud dashboard, you'll be authenticated as an admin. 
+If you want to make API calls from outside the console, you need to pass the admin secret as the `x-hasura-admin-secret` request header.
+
+.. note::
+
+    The admin secret should be treated like a password i.e. it should be kept secret and shouldn't be passed from frontend clients.
+    Refer :ref:`this <authentication>` to set up user authentication.

docs/graphql/cloud/read-replicas.rst

@@ -0,0 +1,42 @@
+.. meta::
+   :description: Hasura Cloud read replicas
+   :keywords: hasura, docs, cloud, read replicas, connections, pool
+
+.. _read_replicas:
+
+Read replicas
+=============
+
+.. contents:: Table of contents
+  :backlinks: none
+  :depth: 1
+  :local:
+
+Introduction
+------------
+
+Hasura Cloud can load balance queries and subscriptions across read replicas while sending all mutations and metadata API calls to the master.
+
+Adding read replica urls
+------------------------
+
+If you have configured your Postgres instances with replicas, the replica URLs can be added to Hasura using the following environment variable in your project ENV Vars tab:
+
+.. code-block:: bash
+
+   HASURA_GRAPHQL_READ_REPLICA_URLS=postgres://user:password@replica-host:5432/db
+
+If you have multiple replicas, their urls can be added as comma separated values.
+
+Connection pool parameters
+--------------------------
+
+Additional environment variables for connection pools, and for read replicas specifically:
+
+``HASURA_GRAPHQL_PG_STRIPES``
+
+``HASURA_GRAPHQL_PG_CONNECTIONS``
+
+``HASURA_GRAPHQL_CONNECTIONS_PER_READ_REPLICA``
+
+``HASURA_GRAPHQL_STRIPES_PER_READ_REPLICA``

docs/graphql/cloud/regression-tests.rst

@@ -0,0 +1,97 @@
+.. meta::
+   :description: Hasura Cloud regression tests
+   :keywords: hasura, docs, cloud, reliability, regression, migration
+
+.. _regression_tests:
+
+Regression tests
+================
+
+.. contents:: Table of contents
+  :backlinks: none
+  :depth: 2
+  :local:
+
+Introduction
+------------
+
+Hasura Cloud includes a comprehensive test bench that lets you seamlessly compile a test suite on each project, executable on any GraphQL Engine instance (ex: staging, prod).
+
+Here's a reference development workflow that is enabled by Hasura Cloud:
+
+#. Build your database schema and configure Hasura as required by your frontend apps or public GraphQL API.
+#. Deploy changes to production after testing them.
+#. Create a regression suite on production.
+#. Iterate on your GraphQL schema to support new features or edits.    
+
+   - Test changes in your dev instance against the production instance’s regression test suite. Fix any issues highlighted by the tests or plan to communicate regressions to affected stakeholders.
+
+#. Run all changes through a CI/CD pipeline   
+
+   - Run Regression tests programmatically for all changes in the team
+
+#. Promote changes to prod
+
+.. thumbnail:: /img/graphql/cloud/reliability/regression-testing-diagram.png
+   :alt: Regression testing process diagram
+
+Manage test suites
+------------------
+
+Each Hasura Cloud project can be configured with a separate test suite. Ideally, you want to create a regression test suite on an project which has received requests with operations you’d like to continue supporting or ensure are not “broken” - production or a shared QA project which receives operations in your app or, if you have a public GraphQL API, those from your consumers.
+
+.. thumbnail:: /img/graphql/cloud/reliability/regression-tests-suites.png
+   :alt: Manage regression test suites
+
+Quick-create tests
+------------------
+
+Add important operations to your test suite with one click by adding them from your project's operation history:
+
+.. thumbnail:: /img/graphql/cloud/reliability/regression-tests-add-operations.png
+   :alt: Add tests to regression test suites
+
+Run test suites
+---------------
+
+A good development workflow would require that tests be run 1) early in the dev process, and 2) automatically with changes, to ensure changes to the schema don't break functionality.
+
+A test suite configured on a Hasura Cloud project can be run on the same instance or any other Hasura Cloud project registered to your team, including local ones. This is how we recommend that you incorporate regression tests into your GraphQL engine workflows:
+
+Run regression tests manually
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Let’s say you’re a developer iterating on a feature and, as part of your work, need to modify your Postgres schema or the Hasura configuration. It is likely that you are doing so by running the console via the Hasura CLI to generate migrations that you can version control. Before committing your changes in git, you should run tests to get an early warning for potential regressions. Your team may want to designate the test suite from your production instance (or a suitable alternative) as the default suite to be used for this, and you can choose to run this test suite on your local or development instance.
+
+.. thumbnail:: /img/graphql/cloud/reliability/regressions-run-prod-tests-on-dev.png
+   :alt: Run regression tests
+
+For example, if the column ‘title’ (in a typical authors and articles schema) has been modified as part of a feature iteration. Assuming the operation from the previous example is part of the test suite on production, here’s how the feedback on this change looks like:
+
+.. thumbnail:: /img/graphql/cloud/reliability/regression-tests-results.png
+   :alt: Regression test results
+
+As you can see, one of the tests fails because it expects a field, title, to be part of the type articles - which is something our proposed change just modified and removed support for.
+
+Run regression tests in CI/CD flow
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. thumbnail:: /img/graphql/cloud/reliability/regression-tests-run-cli.png
+   :alt: Run regression tests via CLI
+
+This command will fetch the entire test suite from Hasura Pro and run the tests against given endpoint using the admin secret and report the result on the terminal. The test run and the results will also be available on the Hasura Console.
+
+You can use the Hasura Pro CLI to programmatically trigger execution of a test suite in your automated testing setup, typically in CI scripts. 
+
+In order to communicate with Hasura’s APIs, the CLI needs to be configured with an API access token (which you can create via your Hasura Cloud settings). If you want to set the token up on a non-interactive environment, like a CI pipeline, you can obtain a token and then add to ``~/.hasura/pro_config.yaml`` with the following format:
+
+.. code-block:: bash
+
+   pat: <token>
+
+
+View test suite results
+-----------------------
+
+.. thumbnail:: /img/graphql/cloud/reliability/regression-tests-past-runs.png
+   :alt: Regression tests past results

docs/graphql/cloud/response-caching.rst

@@ -0,0 +1,66 @@
+.. meta::
+   :description: Query response caching in Hasura Cloud
+   :keywords: hasura, docs, cloud, response, caching
+
+.. _response_caching:
+
+Query response caching
+======================
+
+.. contents:: Table of contents
+  :backlinks: none
+  :depth: 1
+  :local:
+
+Introduction
+------------
+
+Hasura Cloud provides support for caching query responses, in order to 
+improve performance for queries which are executed frequently.
+
+Cached responses are stored in for a period of time in a LRU (least-recently 
+used) cache, and removed from the cache as needed based on usage.
+
+A query's response can be cached only if the following conditions hold:
+
+- The query does not make use of remote schemas or remote joins
+- The query and any related user permissions do not make use of session variables
+- The response JSON is under 100KB in size
+
+Enable caching
+--------------
+
+In order to enable caching for a query response, or to return an existing
+response from the cache (if one exists), simply add the ``@cached`` directive
+to your query:
+
+.. code-block:: graphql
+
+   query MyCachedQuery @cached {
+     users {
+       id
+       name
+     }
+   }
+   
+If the response was cached successfully, the HTTP response will include a
+``X-Hasura-TTL`` header, whose value indicates the maximum number of seconds
+for the returned response to remain in the cache.
+   
+Controlling cache lifetime
+--------------------------
+
+The maximum lifetime of an entry in the cache can be controlled using the ``ttl``
+argument to the ``@cached`` query directive. The value is an integer number of seconds:
+
+.. code-block:: graphql
+
+   query MyCachedQuery @cached(ttl: 120) {
+     users {
+       id
+       name
+     }
+   }
+   
+By default, a response will be cached with a maximum lifetime of 60 seconds.
+The maximum allowed value is 300 seconds (5 minutes).

docs/graphql/cloud/tracing.rst

@@ -0,0 +1,98 @@
+.. meta::
+   :description: Distributed tracing with Hasura Cloud
+   :keywords: hasura, docs, cloud, tracing
+
+.. _tracing:
+
+Distributed tracing
+=======================
+
+.. contents:: Table of contents
+  :backlinks: none
+  :depth: 1
+  :local:
+
+Introduction
+------------
+
+Hasura Cloud has support for *distributed tracing*, a technique for
+debugging Hasura in production in the context of the services it works
+with. These services might include your own Postgres database, any
+remote schemas, event trigger webhook providers, action providers or
+authentication hooks. Distributed tracing attempts to give a unified
+view into the performance characteristics of all of these components of
+your architecture.
+
+Visualizing traces
+------------------
+
+The Hasura Pro console makes it possible to view Hasura's own tracing
+data, by opening the details view for an operation in the Operations
+tab:
+
+.. thumbnail:: /img/graphql/cloud/tracing/tracing-operations-timing.png
+   :alt: View timing data in the Operations tab
+
+Given that other system components will report their own tracing data to
+your APM system, and not to Hasura, it is not possible to give a
+complete picture of a trace, but since Hasura sits in a central position
+in the architecture of many systems, it can often give a reasonably
+comprehensive view of the provenance of data in your system.
+
+For example, Hasura can report interactions with Postgres, remote
+schemas, event trigger webhooks and action handlers.
+
+APM system integration
+----------------------
+
+Hasura will report trace information to your APM or *application
+performance monitoring* system, where it can be correlated with similar
+sources of data from other components of your service architecture.
+
+If you are considering integrating Hasura with your APM system, please
+get in touch so that we can help to coordinate that effort.
+
+Trace propagation
+-----------------
+
+At the boundaries between different services, tracing information needs
+to be shared in order for trace fragments from different systems to be
+correlated with each other in the APM system. This is called *trace
+propagation*.
+
+There are several subtly-incompatible proposals for trace propagation,
+which can make it difficult to arrange for any two services to work
+together.
+
+Propagation to web services
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+For propagation during a call to a web service over HTTP, Hasura
+currently implements the `B3 propagation
+specification <https://github.com/openzipkin/b3-propagation>`__. This
+means that we send trace information in various HTTP headers, which
+should be read and handled by any compatible web services.
+
+If you are unsure how to implement B3 propagation in your own web
+service, the simplest thing to do is to read these headers and pass them
+along to any HTTP services you call which also support B3 propagation,
+including Hasura itself.
+
+In particular, if an event trigger webhook or action handler propagates
+these B3 headers back to Hasura, we will be able to trace the entire
+interaction.
+
+Propagation via Postgres
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+There is no standard method for trace propagation via Postgres
+transactions. For example, event triggers can be invoked by mutations,
+and so their traces should be correlated.
+
+For this reason, we have adopted our own method of propagating a trace
+context in Postgres transactions.
+
+The trace context will be serialized during mutations as a
+transaction-local variable, ``hasura.tracecontext``. This value has the
+Postgres type ``json``, and it can be read in trigger functions and
+propagated to any downstream services.

docs/graphql/core/actions/action-examples.rst.wip

@@ -34,14 +34,14 @@ This page provides reference examples of typical action use cases.
 
   Now we have an action ``updateAddress`` that looks as follows:
 
-  .. thumbnail:: /img/graphql/manual/actions/update-address-action-definition.png
+  .. thumbnail:: /img/graphql/core/actions/update-address-action-definition.png
          :alt: Update address action
          :width: 65%
 
   We can now add an object relationship from the ``updateAddress`` action to the ``authors`` table in our schema.
   We call it ``updatedAddressAuthor``.
 
-  .. thumbnail:: /img/graphql/manual/actions/action-object-relationship.png
+  .. thumbnail:: /img/graphql/core/actions/action-object-relationship.png
          :alt: Object relationship from action
          :width: 65%
 
@@ -90,14 +90,14 @@ This page provides reference examples of typical action use cases.
 
   Now we have an action ``updateAuthor`` that looks as follows:
 
-  .. thumbnail:: /img/graphql/manual/actions/update-author-action-definition.png
+  .. thumbnail:: /img/graphql/core/actions/update-author-action-definition.png
          :alt: Update author action
          :width: 65%
 
   We can now add an array relationship from the ``updateAuthor`` action to the ``articles`` table in our schema.
   We call it ``updatedAuthorArticles``.
 
-  .. thumbnail:: /img/graphql/manual/actions/action-array-relationship.png
+  .. thumbnail:: /img/graphql/core/actions/action-array-relationship.png
          :alt: Array relationship from action
          :width: 65%
 

docs/graphql/core/actions/action-handlers.rst

@@ -183,7 +183,7 @@ For your action, add a header that will act as an action secret.
      Head to the ``Actions -> [action-name]`` tab in the console and scroll down to ``Headers``.
      You can now configure an action secret by adding a header:
 
-     .. thumbnail:: /img/graphql/manual/actions/action-secret-header.png
+     .. thumbnail:: /img/graphql/core/actions/action-secret-header.png
         :alt: Console action secret
         :width: 75%
 

docs/graphql/core/actions/action-permissions.rst

@@ -29,7 +29,7 @@ Set action permissions
      Head to the ``Actions -> [action-name] -> Permissions`` tab in the
      console.
 
-     .. thumbnail:: /img/graphql/manual/actions/actions-permissions.png
+     .. thumbnail:: /img/graphql/core/actions/actions-permissions.png
         :alt: Console action permission
 
      Hit ``Save`` to give the role permission to access the action.

docs/graphql/core/actions/codegen.rst

@@ -41,7 +41,7 @@ Generating handler code for your action
     You can select the framework of your choice to get the corresponding
     handler boilerplate code.
 
-    .. thumbnail:: /img/graphql/manual/actions/console-codegen-tab.png
+    .. thumbnail:: /img/graphql/core/actions/console-codegen-tab.png
        :alt: Console codegen tab
 
 
@@ -59,17 +59,17 @@ Generating handler code for your action
 
     1. Choose which framework you want to codegen for:
 
-       .. thumbnail:: /img/graphql/manual/actions/cli-framework-prompt.png
+       .. thumbnail:: /img/graphql/core/actions/cli-framework-prompt.png
           :alt: CLI Framework Prompt
 
     2. Choose if you also wish to clone a starter kit for the chosen framework:
 
-       .. thumbnail:: /img/graphql/manual/actions/cli-starter-kit-prompt.png
+       .. thumbnail:: /img/graphql/core/actions/cli-starter-kit-prompt.png
           :alt: CLI Starter Kit Prompt
 
     3. Choose a path where you want to output the auto-generated code files
 
-       .. thumbnail:: /img/graphql/manual/actions/cli-output-dir-prompt.png
+       .. thumbnail:: /img/graphql/core/actions/cli-output-dir-prompt.png
           :alt: CLI Starter Kit Prompt
 
 

docs/graphql/core/actions/create.rst

@@ -96,7 +96,7 @@ in the GraphQL schema.
      Go to the ``Actions`` tab on the console and click on ``Create``. This will
      take you to a page like this:
 
-     .. thumbnail:: /img/graphql/manual/actions/mutation-action-create.png
+     .. thumbnail:: /img/graphql/core/actions/mutation-action-create.png
         :alt: Console action create
         :width: 70%
 
@@ -275,7 +275,7 @@ the GraphQL schema.
      Go to the ``Actions`` tab on the console and click on ``Create``. This will
      take you to a page like this:
 
-     .. thumbnail:: /img/graphql/manual/actions/query-action-create.png
+     .. thumbnail:: /img/graphql/core/actions/query-action-create.png
         :alt: Console action create
         :width: 70%
 

docs/graphql/core/actions/derive.rst

@@ -75,13 +75,13 @@ derive our action:
 
      Next hit the ``Derive action`` button as shown below:
 
-     .. thumbnail:: /img/graphql/manual/actions/actions-derive-button.png
+     .. thumbnail:: /img/graphql/core/actions/actions-derive-button.png
         :alt: Console derive action button
 
      This will redirect you to the ``Add a new action`` page with the action
      definition auto filled.
 
-     .. thumbnail:: /img/graphql/manual/actions/actions-derive-types.png
+     .. thumbnail:: /img/graphql/core/actions/actions-derive-types.png
         :alt: Console derived action types
 
 
@@ -149,7 +149,7 @@ the action back to the original operation.
     You can select the framework of your choice to get the corresponding
     handler boilerplate code.
 
-    .. thumbnail:: /img/graphql/manual/actions/actions-derive-codegen.png
+    .. thumbnail:: /img/graphql/core/actions/actions-derive-codegen.png
        :alt: Console derived action codegen
 
     .. note::

docs/graphql/core/actions/index.rst

@@ -20,7 +20,7 @@ logic using custom queries and mutations. Actions can be
 added to Hasura to handle various use cases such as data validation, data
 enrichment from external sources and any other complex business logic.
 
-.. thumbnail:: /img/graphql/manual/actions/actions-arch.png
+.. thumbnail:: /img/graphql/core/actions/actions-arch.png
    :class: no-shadow
    :alt: Actions high level architecture
 

docs/graphql/core/actions/reuse-types-actions.rst

@@ -98,7 +98,7 @@ You can create relationships for custom output types by:
 
      Set the output type relationship as shown below:
 
-     .. thumbnail:: /img/graphql/manual/actions/actions-relationship.png
+     .. thumbnail:: /img/graphql/core/actions/actions-relationship.png
         :alt: Console action relationship
 
      Hit ``Save`` to create the relationship.

docs/graphql/core/api-reference/config.rst

@@ -12,6 +12,9 @@ Config API Reference
   :depth: 1
   :local:
 
+Introduction
+------------
+
 The Config API is an admin only endpoint which gives info on the server
 configuration.
 

docs/graphql/core/api-reference/explain.rst

@@ -12,6 +12,9 @@ Explain API Reference
   :depth: 1
   :local:
 
+Introduction
+------------
+
 The Explain API is used to analyse queries and subscriptions. It returns a list of Postgres plans for a query and a single Postgres plan for a subscription, based
 on the defined permissions.
 

docs/graphql/core/api-reference/graphql-api/index.rst

@@ -12,6 +12,9 @@ GraphQL API Reference
   :depth: 1
   :local:
 
+Introduction
+------------
+
 All GraphQL requests for queries, subscriptions and mutations are made to the GraphQL API.
 
 Endpoint

docs/graphql/core/api-reference/health.rst

@@ -12,6 +12,9 @@ Health check API Reference
   :depth: 1
   :local:
 
+Introduction
+------------
+
 The Health API is a public endpoint which gives info on the server health.
 
 Endpoint

docs/graphql/core/api-reference/pgdump.rst

@@ -12,6 +12,9 @@ PG Dump API Reference
   :depth: 1
   :local:
 
+Introduction
+------------
+
 The PG Dump API is an admin-only endpoint that can be used to execute ``pg_dump`` on the
 Postgres instance that Hasura is configured with.
 

docs/graphql/core/api-reference/postgresql-types.rst

@@ -14,6 +14,9 @@ API Reference - Supported PostgreSQL Types
 
 .. _types_table:
 
+Introduction
+------------
+
 List of PostgreSQL types supported by the Hasura GraphQL engine with their equivalent Hasura types:
 
 .. csv-table::

docs/graphql/core/api-reference/schema-metadata-api/actions.rst

@@ -12,6 +12,9 @@ Schema/Metadata API Reference: Actions
   :depth: 1
   :local:
 
+Introduction
+------------
+
 **actions** are user defined mutations with custom business logic.
 
 .. _create_action:

docs/graphql/core/api-reference/schema-metadata-api/computed-field.rst

@@ -12,6 +12,9 @@ Schema/Metadata API Reference: Computed Fields
   :depth: 1
   :local:
 
+Introduction
+------------
+
 **computed field** is an extra field added to a table, its value is
 computed via an SQL function which has the table row type as an input argument.
 Currenty, the Hasura GraphQL engine supports functions returning

docs/graphql/core/api-reference/schema-metadata-api/custom-functions.rst

@@ -12,6 +12,9 @@ Schema/Metadata API Reference: Custom Functions
   :depth: 1
   :local:
 
+Introduction
+------------
+
 Track/untrack a custom SQL function in the Hasura GraphQL engine.
 
 Only tracked custom functions are available for querying/mutating/subscribing data over the GraphQL API.

docs/graphql/core/api-reference/schema-metadata-api/custom-types.rst

@@ -7,6 +7,14 @@
 Schema/Metadata API Reference: Custom Types
 ===========================================
 
+.. contents:: Table of contents
+  :backlinks: none
+  :depth: 1
+  :local:
+
+Introduction
+------------
+
 **Custom Types** are user-defined GraphQL types which help to define :ref:`Actions <api_actions>`.
 
 .. _set_custom_types:

docs/graphql/core/api-reference/schema-metadata-api/event-triggers.rst

@@ -12,6 +12,9 @@ Schema/Metadata API Reference: Event Triggers
   :depth: 1
   :local:
 
+Introduction
+------------
+
 Event triggers are used to capture database changes and send them to a configured webhook.
 
 .. _create_event_trigger:

docs/graphql/core/api-reference/schema-metadata-api/index.rst

@@ -12,6 +12,9 @@ Schema / Metadata API Reference
   :depth: 1
   :local:
 
+Introduction
+------------
+
 The schema / metadata API provides the following features:
 
 1. Execute SQL on the underlying Postgres database, supports schema modifying actions.

docs/graphql/core/api-reference/schema-metadata-api/manage-metadata.rst

@@ -12,6 +12,9 @@ Schema/Metadata API Reference: Manage metadata
   :depth: 1
   :local:
 
+Introduction
+------------
+
 APIs to manage Hasura metadata which is stored in ``hdb_catalog`` schema.
 
 .. _export_metadata:

docs/graphql/core/api-reference/schema-metadata-api/permission.rst

@@ -12,6 +12,9 @@ Schema/Metadata API Reference: Permissions
   :depth: 1
   :local:
 
+Introduction
+------------
+
 The permission layer is designed to restrict the operations that can be
 performed by various users. Permissions can be defined on various operations
 (insert/select/update/delete) at a role level granularity. By default, the ``admin``

docs/graphql/core/api-reference/schema-metadata-api/query-collections.rst

@@ -12,6 +12,9 @@ Schema/Metadata API Reference: Query collections
   :depth: 1
   :local:
 
+Introduction
+------------
+
 Group queries using query collections.
 
 Create/drop query collections and add/drop a query to a collection using the following query types.

docs/graphql/core/api-reference/schema-metadata-api/relationship.rst

@@ -12,6 +12,9 @@ Schema/Metadata API Reference: Relationships
   :depth: 1
   :local:
 
+Introduction
+------------
+
 When retrieving data from tables, it is very helpful if we can also
 fetch the related data alongside the columns. This is where relationships come
 in. They can be considered as pseudo columns for a table to access the related

docs/graphql/core/api-reference/schema-metadata-api/remote-relationships.rst

@@ -10,6 +10,9 @@ Schema/Metadata API Reference: Remote Relationships
   :depth: 1
   :local:
 
+Introduction
+------------
+
 Remote Relationships allow you to join tables with remote schemas.
 
 .. _create_remote_relationship:

docs/graphql/core/api-reference/schema-metadata-api/remote-schemas.rst

@@ -12,6 +12,9 @@ Schema/Metadata API Reference: Remote schemas
   :depth: 1
   :local:
 
+Introduction
+------------
+
 Add/Remove a remote GraphQL server as remote schema in Hasura GraphQL engine.
 
 .. _add_remote_schema:

docs/graphql/core/api-reference/schema-metadata-api/scheduled-triggers.rst

@@ -10,6 +10,9 @@ Schema/Metadata API Reference: Scheduled Triggers
   :depth: 1
   :local:
 
+Introduction
+------------
+
 Scheduled triggers are used to invoke webhooks based on a timestamp or cron.
 
 .. _create_cron_trigger:

docs/graphql/core/api-reference/schema-metadata-api/table-view.rst

@@ -12,6 +12,9 @@ Schema/Metadata API Reference: Tables/Views
   :depth: 1
   :local:
 
+Introduction
+------------
+
 Track/untrack a table/view in Hasura GraphQL engine.
 
 Only tracked tables/views are available for querying/mutating/subscribing data over the GraphQL API.

docs/graphql/core/api-reference/version.rst

@@ -12,6 +12,8 @@ Version API Reference
   :depth: 1
   :local:
 
+Introduction
+------------
 
 The ``/v1/version`` is a public endpoint that responds with the current server version in JSON format.
 

docs/graphql/core/auth/authentication/index.rst

@@ -39,7 +39,7 @@ rules.
 
 Here's how a GraphQL request is processed in webhook mode:
 
-.. thumbnail:: /img/graphql/manual/auth/auth-webhook-overview.png
+.. thumbnail:: /img/graphql/core/auth/auth-webhook-overview.png
    :alt: Authentication using webhooks
 
 2. JWT (JSON Web Token)
@@ -51,7 +51,7 @@ evaluate access control rules.
 
 Here's how a GraphQL query is processed in JWT mode:
 
-.. thumbnail:: /img/graphql/manual/auth/auth-jwt-overview.png
+.. thumbnail:: /img/graphql/core/auth/auth-jwt-overview.png
    :alt: Authentication using JWT
 
 **See more details at:**

docs/graphql/core/auth/authentication/jwt.rst

@@ -21,7 +21,7 @@ The idea is that your auth server will return JWT tokens, which are decoded and
 verified by the GraphQL engine, to authorize and get metadata about the request
 (``x-hasura-*`` values).
 
-.. thumbnail:: /img/graphql/manual/auth/jwt-auth.png
+.. thumbnail:: /img/graphql/core/auth/jwt-auth.png
    :alt: Authentication using JWT
 
 The JWT is decoded, the signature is verified, then it is asserted that the
@@ -133,7 +133,8 @@ JSON object:
      "claims_namespace_path":"<optional-json-path-to-the-claims>",
      "claims_format": "json|stringified_json",
      "audience": <optional-string-or-list-of-strings-to-verify-audience>,
-     "issuer": "<optional-string-to-verify-issuer>"
+     "issuer": "<optional-string-to-verify-issuer>",
+     "claims_map": "<optional-object-of-session-variable-to-claim-jsonpath-or-literal-value>"
    }
 
 (``type``, ``key``) pair or ``jwk_url``, **one of them has to be present**.
@@ -255,8 +256,6 @@ set to ``$.hasura.claims``:
    values set. If neither keys are set, then the default value of
    ``claims_namespace`` i.e. https://hasura.io/jwt/claims will be used.
 
-``claims_format``
-^^^^^^^^^^^^^^^^^
 This is an optional field, with only the following possible values:
 - ``json``
 - ``stringified_json``
@@ -371,6 +370,130 @@ Examples:
    that you can set this field to the appropriate value.
 
 
+``claims_map``
+^^^^^^^^^^^^^^
+This is an optional field. Certain providers might not allow adding custom claims.
+In such a case, you can map Hasura session variables with existing JWT claims
+using ``claims_map``. The ``claims_map`` is a JSON object where keys are session
+variables and values can be a JSON path (with a default value option, when the key
+specified by the JSON path doesn't exist) or a literal value.
+
+The literal values should be a ``String``, except for the ``x-hasura-allowed-roles`` claim
+which expects a ``String`` array.
+
+The value of a claim referred by a JSON path must be a ``String``.
+To use the JSON path value, the path needs to be given in a JSON object with ``path``
+as the key and the JSON path as the value:
+
+.. code-block:: json
+
+   {
+     "path" : "$.user.all_roles",
+   }
+
+.. code-block:: json
+
+   {
+     "path" : "$.roles.default",
+     "default": "user"
+   }
+
+**Example: JWT config with JSON path values**
+
+.. code-block:: json
+
+  {
+    "sub": "1234567890",
+    "name": "John Doe",
+    "admin": true,
+    "iat": 1516239022,
+    "user": {
+      "id": "ujdh739kd"
+    },
+    "hasura": {
+      "all_roles": ["user", "editor"],
+    }
+
+  }
+
+The mapping for ``x-hasura-allowed-roles``, ``x-hasura-default-role`` and ``x-hasura-user-id`` session
+variables can be specified in the ``claims_map`` configuration as follows:
+
+.. code-block:: json
+
+  {
+    "type":"RS512",
+    "key": "-----BEGIN PUBLIC KEY-----\nMIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDdlatRjRjogo3WojgGHFHYLugd\nUWAY9iR3fy4arWNA1KoS8kVw33cJibXr8bvwUAUparCwlvdbH6dvEOfou0/gCFQs\nHUfQrSDv+MuSUMAe8jzKE4qW+jK+xQU9a03GUnKHkkle+Q0pX/g6jXZ7r1/xAK5D\no2kQ+X5xK9cipRgEKwIDAQAB\n-----END PUBLIC KEY-----\n",
+    "claims_map": {
+      "x-hasura-allowed-roles": {"path":"$.hasura.all_roles"},
+      "x-hasura-default-role": {"path":"$.hasura.all_roles[0]"},
+      "x-hasura-user-id": {"path":"$.user.id"}
+    }
+  }
+
+**Example: JWT config with JSON path values and default values**
+
+.. code-block:: json
+
+  {
+    "sub": "1234567890",
+    "name": "John Doe",
+    "admin": true,
+    "iat": 1516239022,
+    "hasura": {
+      "all_roles": ["user", "editor"],
+    }
+
+  }
+
+.. code-block:: json
+
+  {
+    "type":"RS512",
+    "key": "-----BEGIN PUBLIC KEY-----\nMIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDdlatRjRjogo3WojgGHFHYLugd\nUWAY9iR3fy4arWNA1KoS8kVw33cJibXr8bvwUAUparCwlvdbH6dvEOfou0/gCFQs\nHUfQrSDv+MuSUMAe8jzKE4qW+jK+xQU9a03GUnKHkkle+Q0pX/g6jXZ7r1/xAK5D\no2kQ+X5xK9cipRgEKwIDAQAB\n-----END PUBLIC KEY-----\n",
+    "claims_map": {
+      "x-hasura-allowed-roles": {"path":"$.hasura.all_roles"},
+      "x-hasura-default-role": {"path":"$.hasura.all_roles[0]"},
+      "x-hasura-user-id": {"path":"$.user.id","default":"ujdh739kd"}
+    }
+  }
+
+In the above case, since the ``$.user.id`` doesn't exist in the JWT token, the default
+value of the ``x-hasura-user-id`` i.e "ujdh739kd" will be used
+
+
+**Example: JWT config containing literal values**
+
+.. code-block:: json
+
+  {
+    "sub": "1234567890",
+    "name": "John Doe",
+    "admin": true,
+    "iat": 1516239022,
+    "user": {
+      "id": "ujdh739kd"
+    }
+  }
+
+The corresponding JWT config should be:
+
+.. code-block:: json
+
+  {
+    "type":"RS512",
+    "key": "-----BEGIN PUBLIC KEY-----\nMIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDdlatRjRjogo3WojgGHFHYLugd\nUWAY9iR3fy4arWNA1KoS8kVw33cJibXr8bvwUAUparCwlvdbH6dvEOfou0/gCFQs\nHUfQrSDv+MuSUMAe8jzKE4qW+jK+xQU9a03GUnKHkkle+Q0pX/g6jXZ7r1/xAK5D\no2kQ+X5xK9cipRgEKwIDAQAB\n-----END PUBLIC KEY-----\n",
+    "claims_map": {
+      "x-hasura-allowed-roles": ["user","editor"],
+      "x-hasura-default-role": "user",
+      "x-hasura-user-id": {"path":"$.user.id"}
+    }
+
+  }
+
+In the above example, the ``x-hasura-allowed-roles`` and ``x-hasura-default-role`` values are set in the JWT
+config and the value of the ``x-hasura-user-id`` is a JSON path to the value in the JWT token.
+
 
 Examples
 ^^^^^^^^
@@ -543,7 +666,7 @@ https://hasura.io/jwt-config.
 The config generated from this page can be directly pasted in yaml files and command line arguments as it takes
 care of escaping new lines.
 
-.. thumbnail:: /img/graphql/manual/auth/jwt-config-generated.png
+.. thumbnail:: /img/graphql/core/auth/jwt-config-generated.png
    :width: 75%
    :alt: Generating JWT config
 

docs/graphql/core/auth/authentication/webhook.rst

@@ -17,7 +17,7 @@ Introduction
 
 You can configure the GraphQL engine to use a webhook to authenticate all incoming requests to the Hasura GraphQL engine server. 
 
-.. thumbnail:: /img/graphql/manual/auth/webhook-auth.png
+.. thumbnail:: /img/graphql/core/auth/webhook-auth.png
    :alt: Authentication using webhooks
 
 .. admonition:: Prerequisite

docs/graphql/core/auth/authorization/basics.rst

@@ -18,7 +18,7 @@ Introduction
 
 To understand the basics of access control in Hasura, let's take a look at this analogy to a SQL query: 
 
-.. thumbnail:: /img/graphql/manual/auth/permissions-rule-analogy.png
+.. thumbnail:: /img/graphql/core/auth/permissions-rule-analogy.png
   :width: 70%
   :alt: Understanding access control in Hasura
 
@@ -80,7 +80,7 @@ Head to the ``GraphiQL`` tab in your console and try out the below query:
 You'll see that this results in a response that contains all the authors because by default the GraphQL
 query is accepted with **admin** permissions.
 
-.. thumbnail:: /img/graphql/manual/auth/fetch-authors.png
+.. thumbnail:: /img/graphql/core/auth/fetch-authors.png
    :alt: Run a query without access control
 
 Define access control rules
@@ -90,7 +90,7 @@ Now let's define an access control rule for the ``author`` table for a role ``us
 **Permissions** section of the table (``Data`` --> <table> --> ``Permissions`` tab) and define permissions
 as shown below:
 
-.. thumbnail:: /img/graphql/manual/auth/permission-basics-simple-example.png
+.. thumbnail:: /img/graphql/core/auth/permission-basics-simple-example.png
    :alt: Define access control rules
 
 This permission rule reads as: "*For the role* ``user`` *, table* ``author`` *and operation* ``select``/``query``,
@@ -103,7 +103,7 @@ Let's run the same query as above but now with the ``X-Hasura-Role`` and ``X-Has
 variables also included to indicate role and user information. These session variables are passed in
 the ``Request Headers`` section of ``GraphiQL`` as highlighted below:
 
-.. thumbnail:: /img/graphql/manual/auth/permission-basics-query-with-access-control.png
+.. thumbnail:: /img/graphql/core/auth/permission-basics-query-with-access-control.png
    :alt: Run a query with access control
 
 As you can see, the results are now filtered based on the access control rule for the role ``user``

docs/graphql/core/auth/authorization/common-roles-auth-examples.rst

@@ -12,6 +12,9 @@ Access control examples
   :depth: 1
   :local:
 
+Introduction
+------------
+
 This is a guide to help you set up a basic authorization architecture for your GraphQL fields. It is recommended
 that you first check out :ref:`roles_variables` and :ref:`permission_rules`
 that will be referred to throughout this guide.
@@ -31,7 +34,7 @@ Anonymous (not logged in) users
 - Choose the right set of columns that will get exposed in the GraphQL schema as fields. Ensure that sensitive
   information will not be exposed.
 
-.. thumbnail:: /img/graphql/manual/auth/anonymous-role-examples.png
+.. thumbnail:: /img/graphql/core/auth/anonymous-role-examples.png
    :class: no-shadow
    :alt: Access control for an anonymous role
 
@@ -47,7 +50,7 @@ Logged-in users
 - Note that the ``X-Hasura-User-Id`` is a :ref:`dynamic session variable<roles_variables>` that comes in from
   your :ref:`auth webhook's <auth_webhooks>` response, or as a request header if you're testing.
 
-.. thumbnail:: /img/graphql/manual/auth/user-select-graphiql.png
+.. thumbnail:: /img/graphql/core/auth/user-select-graphiql.png
    :class: no-shadow
    :alt: Access control for a logged-in user
 
@@ -64,7 +67,7 @@ organisation either in the same table or via a related table.
 - ``X-Hasura-Org-Id`` is a :ref:`dynamic variable <roles_variables>` that is returned by your
   :ref:`auth webhook <auth_webhooks>` for an incoming GraphQL request.
 
-.. thumbnail:: /img/graphql/manual/auth/org-manager-graphiql.png
+.. thumbnail:: /img/graphql/core/auth/org-manager-graphiql.png
    :class: no-shadow
    :alt: Access control for a manager of an organisation
 
@@ -84,7 +87,7 @@ Let's say the "ownership" or "visibility" information for a data model (table) i
   - This reads as: Allow the role collaborator to select if ``article.collaborators`` has a ``collaborator_id``
     equal to that of ``X-Hasura-User-Id``.
 
-.. thumbnail:: /img/graphql/manual/auth/collaborator-relationship.png
+.. thumbnail:: /img/graphql/core/auth/collaborator-relationship.png
    :class: no-shadow
    :alt: Access control for collaborators of an article
 
@@ -149,7 +152,7 @@ Database Schema
 
 The following is a reference database schema for our example:
 
-.. thumbnail:: /img/graphql/manual/auth/multirole-example-db-schema.png
+.. thumbnail:: /img/graphql/core/auth/multirole-example-db-schema.png
    :alt: Database schema example for multiple roles per user
 
 Based on this schema, we'll create the following tables:
@@ -196,7 +199,7 @@ Relationships
 
 Create an array relationship named ``reviewers`` based on the foreign key constraint ``reviewers`` :: ``article_id``  →  ``articles`` :: ``id``:
 
-.. thumbnail:: /img/graphql/manual/auth/multirole-example-reviewers-array-relationship.png
+.. thumbnail:: /img/graphql/core/auth/multirole-example-reviewers-array-relationship.png
      :class: no-shadow
      :alt: Create an array relationship
 
@@ -240,7 +243,7 @@ Permissions for role ``author``
   
   b) :ref:`Column presets <column_presets>`: Session-variable-based column preset for the ``author_id`` column to automatically insert the user's ID i.e. the ``X-Hasura-User-Id`` session-variable's value. It also helps us avoid explicitly passing the user's ID in the insert mutation.
 
-  .. thumbnail:: /img/graphql/manual/auth/multirole-example-author-insert.png
+  .. thumbnail:: /img/graphql/core/auth/multirole-example-author-insert.png
      :alt: Permissions for the role author
 
   Notice how we don't need to have an explicit row-level permission (*a custom check*) as only authenticated users with the role ``author`` can perform this action. As we have a column preset for the ``author_id`` column that automatically takes the author's ID (*and the* ``id`` *column is an auto-increment integer field*), we only need to allow access to the ``title`` column.
@@ -249,7 +252,7 @@ Permissions for role ``author``
 
   Again, we'll  use **column-level** permissions to restrict access to certain columns. Additionally, we need to define row-level permissions (*a custom check*) to restrict access to only those articles authored by the current user:
 
-  .. thumbnail:: /img/graphql/manual/auth/multirole-example-author-select.png
+  .. thumbnail:: /img/graphql/core/auth/multirole-example-author-select.png
      :alt: Column access for the role author
   
   The row-level permission rule shown here translates to "*if the value in the* ``author_id`` *column of this row is equal to the user's ID i.e. the* ``X-Hasura-User-Id`` *session-variable's value, allow access to it*". 
@@ -261,7 +264,7 @@ Permissions for role ``reviewer``
   
   For this use-case, we'll use :ref:`relationship or nested-object permissions<relationships-in-permissions>` based on the array relationship ``reviewers`` to restrict access to assigned articles only.
 
-  .. thumbnail:: /img/graphql/manual/auth/multirole-example-reviewer-update.png
+  .. thumbnail:: /img/graphql/core/auth/multirole-example-reviewer-update.png
      :alt: Permissions for the role reviewer
 
   The array-relationship based permission rule in the above image reads as "*if the ID of any reviewer assigned to this article is equal to the user's ID i.e. the* ``X-Hasura-User-Id`` *session-variable's value, allow access to it*". The columns' access is restricted using the column-level permissions highlighted above.
@@ -270,7 +273,7 @@ Permissions for role ``reviewer``
 
   This permission rule is pretty much the same as the one for update, the only difference being the  column-level permissions.  
 
-  .. thumbnail:: /img/graphql/manual/auth/multirole-example-reviewer-select.png
+  .. thumbnail:: /img/graphql/core/auth/multirole-example-reviewer-select.png
      :alt: Column access for the role reviewer
 
 Permissions for role ``editor``
@@ -280,14 +283,14 @@ Permissions for role ``editor``
 
   This is a straightforward rule - there's no need for any row-level permissions since editors have access to all rows and they can *read* all columns.
 
-  .. thumbnail:: /img/graphql/manual/auth/multirole-example-editor-select.png
+  .. thumbnail:: /img/graphql/core/auth/multirole-example-editor-select.png
      :alt: Permissions for the role editor
 
 * **Allow editors to update an article**
 
   There's no need for row-level permissions in this case either but we need to restrict access to certain columns only:
 
-  .. thumbnail:: /img/graphql/manual/auth/multirole-example-editor-update.png
+  .. thumbnail:: /img/graphql/core/auth/multirole-example-editor-update.png
      :alt: Column access for the role editor
 
 

docs/graphql/core/auth/authorization/index.rst

@@ -23,7 +23,7 @@ session variables. Other session variables can be passed by your auth service as
 
 **For example:**
 
-.. thumbnail:: /img/graphql/manual/auth/hasura-perms.png
+.. thumbnail:: /img/graphql/core/auth/hasura-perms.png
    :width: 80 %
    :alt: Create a permission rule
 

docs/graphql/core/auth/authorization/modeling-roles.rst.wip

@@ -18,7 +18,7 @@ Roles can be typically be modeled in two ways:
 1. **Hierarchical roles**: Access scopes are nested depending on available roles. `Roles in Github for organisations <https://help.github.com/en/articles/managing-peoples-access-to-your-organization-with-roles>`_
    is a great example of such modelling where access scopes are inherited by deeper roles:
 
-   .. thumbnail:: /img/graphql/manual/auth/github-org-hierarchical-roles.png
+   .. thumbnail:: /img/graphql/core/auth/github-org-hierarchical-roles.png
 
 2. **Flat roles**: Non-hierarchical roles with each role requiring an independent access scope to be defined.
 

docs/graphql/core/auth/authorization/permission-rules.rst

@@ -18,7 +18,7 @@ Introduction
 Access control rules in Hasura are defined at a role, table and action (*insert, update, select, delete*)
 level granularity:
 
-.. thumbnail:: /img/graphql/manual/auth/permission-rule-granularity.png
+.. thumbnail:: /img/graphql/core/auth/permission-rule-granularity.png
    :alt: Access control rules in Hasura
 
 Requests to Hasura should contain the reserved session variable ``X-Hasura-Role`` to indicate the requesting
@@ -108,11 +108,11 @@ See the :ref:`API reference <MetadataOperator>` for a list of all supported colu
 types:
 
 
-.. thumbnail:: /img/graphql/manual/auth/operators-for-integer-types.png
+.. thumbnail:: /img/graphql/core/auth/operators-for-integer-types.png
    :width: 40%
    :alt: Column operators for integer types
 
-.. thumbnail:: /img/graphql/manual/auth/operators-for-text-types.png
+.. thumbnail:: /img/graphql/core/auth/operators-for-text-types.png
    :width: 40%
    :alt: Column operators for text types
 
@@ -122,19 +122,19 @@ Using boolean expressions
 The following is an example of a simple boolean expression to restrict access for ``select`` to rows where
 the value in the ``id`` column is greater than 10:
 
-.. thumbnail:: /img/graphql/manual/auth/simple-boolean-expression.png
+.. thumbnail:: /img/graphql/core/auth/simple-boolean-expression.png
    :alt: Using boolean expressions to build rules
 
 You can construct more complex boolean expressions using the ``_and``, ``_or`` and ``not`` operators:
 
-.. thumbnail:: /img/graphql/manual/auth/boolean-operators.png
+.. thumbnail:: /img/graphql/core/auth/boolean-operators.png
    :alt: Using more complex boolean expressions to build rules
 
 **For example**, using the ``_and`` operator, you can construct a rule to restrict access for ``select`` to rows where
 the value in the ``id`` column is greater than 10 **and** the value in the ``name`` column starts with "a"
 or "A":
 
-.. thumbnail:: /img/graphql/manual/auth/composite-boolean-expression.png
+.. thumbnail:: /img/graphql/core/auth/composite-boolean-expression.png
    :alt: Example of a rule with the _and operator
 
 Using session variables
@@ -148,7 +148,7 @@ to construct a rule to restrict access for ``select`` to rows in the ``articles`
 ``id`` column is equal to the value in the session variable (*assuming this variable is being used to indicate
 the author's ID*):
 
-.. thumbnail:: /img/graphql/manual/auth/session-variables-in-permissions-simple-example.png
+.. thumbnail:: /img/graphql/core/auth/session-variables-in-permissions-simple-example.png
    :alt: Using session variables to build rules
 
 .. _relationships-in-permissions:
@@ -164,7 +164,7 @@ called ``agent`` (*an author can have an agent*) and we want to allow users with
 the details of the authors who they manage in ``authors`` table. We can define the following permission rule
 that uses the aforementioned object relationship:
 
-.. thumbnail:: /img/graphql/manual/auth/nested-object-permission-simple-example.png
+.. thumbnail:: /img/graphql/core/auth/nested-object-permission-simple-example.png
    :alt: Using a nested object to build rules
 
 This permission rule reads as "*if the author's agent's*  ``id``  *is the same as the requesting user's*
@@ -191,7 +191,7 @@ our table.
 column in the ``users`` table is set to ``true``. Let's assume the user's id is passed in the ``X-Hasura-User-ID``
 session variable.
 
-.. thumbnail:: /img/graphql/manual/auth/exists-permission-example.png
+.. thumbnail:: /img/graphql/core/auth/exists-permission-example.png
    :alt: Use an unrelated table to build rules
 
 This permission rule reads as "*if there exists a row in the table* ``users`` *whose*  ``id``  *is the same as the requesting user's*
@@ -204,7 +204,7 @@ Column-level permissions
 Column-level permissions determine access to columns in the rows that are accessible based on row-level
 permissions. These permissions are simple selections:
 
-.. thumbnail:: /img/graphql/manual/auth/column-level-permissions.png
+.. thumbnail:: /img/graphql/core/auth/column-level-permissions.png
    :alt: Column level permissions
 
 In this example, the role ``author`` has only partial access to columns of the accessible rows for
@@ -218,7 +218,7 @@ Row fetch limit
 In the case of ``select`` operations, the number of rows to be returned in the response can be limited
 using this configuration:
 
-.. thumbnail:: /img/graphql/manual/auth/limit-rows-for-select.png
+.. thumbnail:: /img/graphql/core/auth/limit-rows-for-select.png
    :alt: Row fetch limit
 
 In the above example, this configuration  restricts the number of accessible rows (*based on the rule*:
@@ -232,7 +232,7 @@ Aggregation queries permissions
 In the case of ``select`` operations, access to :ref:`aggregation queries <aggregation_queries>`
 can be restricted for a given role using this configuration.
 
-.. thumbnail:: /img/graphql/manual/auth/aggregation-query-permissions.png
+.. thumbnail:: /img/graphql/core/auth/aggregation-query-permissions.png
    :alt: Aggregation queries permissions
 
 In the above example, the role ``user`` is allowed to make aggregation queries.

docs/graphql/core/auth/authorization/reference-permissions.rst.wip

@@ -13,7 +13,7 @@ How permissions work
 
 Access control rules in Hasura are defined at a role, table and action (*insert, update, select, delete*) level granulaity:
 
-.. thumbnail:: /img/graphql/manual/auth/permission-rule-granularity.png
+.. thumbnail:: /img/graphql/core/auth/permission-rule-granularity.png
 
 Requests to Hasura should contain the reserved session variable ``X-Hasura-Role`` to indicate the requesting user's role, and the table and action information is inferred from the request itself. This information is used to determine the right permission rule to be applied (*if one has been defined*) to the incoming request.
 
@@ -65,7 +65,7 @@ If you make this query as an admin in the Graphiql section of the console and cl
 
 Let's say you now define the following permission rule on the ``authors`` table (*as described in the example* :doc:`here <basics>`):
 
-.. thumbnail:: /img/graphql/manual/auth/permission-basics-simple-example.png
+.. thumbnail:: /img/graphql/core/auth/permission-basics-simple-example.png
 
 If you were to run the same query with the role ``user`` (``X-Hasura-Role`` = ``user``) and as a user with ``id`` = ``1`` (``X-Hasura-User-ID`` = ``1``) and hit the **Analyze** button, you will see the following generated SQL:
 
@@ -149,24 +149,24 @@ Type-based operators (*depending on the column type*) are available for construc
 E.g. the following two images illustrate the different operators available for ``integer`` and ``text`` types:
 
 
-.. thumbnail:: /img/graphql/manual/auth/operators-for-integer-types.png
+.. thumbnail:: /img/graphql/core/auth/operators-for-integer-types.png
 
-.. thumbnail:: /img/graphql/manual/auth/operators-for-text-types.png
+.. thumbnail:: /img/graphql/core/auth/operators-for-text-types.png
 
 **Using boolean expressions**
 #############################
 
 The following is an example of a simple boolean expression to restrict access for ``select`` to rows where the value in the ``id`` column is greater than 10:
 
-.. thumbnail:: /img/graphql/manual/auth/simple-boolean-expression.png
+.. thumbnail:: /img/graphql/core/auth/simple-boolean-expression.png
 
 You can construct more complex boolean expression using the ``_and``, ``_or`` and ``not`` operators:
 
-.. thumbnail:: /img/graphql/manual/auth/boolean-operators.png
+.. thumbnail:: /img/graphql/core/auth/boolean-operators.png
 
 E.g. using the ``_and`` operator, you can construct a rule to restrict access for ``select`` to rows where the value in the ``id`` column is greater than 10 **and** the value in the ``name`` column starts with "a" or "A":
 
-.. thumbnail:: /img/graphql/manual/auth/composite-boolean-expression.png
+.. thumbnail:: /img/graphql/core/auth/composite-boolean-expression.png
 
 .. Using roles
 .. ###########
@@ -179,7 +179,7 @@ Session variable, that have been resolved from authentication tokens by either y
 
 E.g. to allow an ``author`` to access only their articles, you can use the ``X-Hasura-User-ID`` session variable to construct a rule to restrict access for ``select`` to rows in the ``articles`` table where the value in the ``id`` column is equal to the value in the session variable (*assuming this variable is being used to indicate the author's ID*):
 
-.. thumbnail:: /img/graphql/manual/auth/session-variables-in-permissions-simple-example.png
+.. thumbnail:: /img/graphql/core/auth/session-variables-in-permissions-simple-example.png
 
 .. _relationships-in-permissions:
 
@@ -190,7 +190,7 @@ You can leverage :doc:`relationships <../../schema/relationships/index>` to defi
 
 For e.g. let's say you have an object relationship called ``agent`` from the ``authors`` table to another table called ``agent`` (*an author can have an agent*) and we want to allow users with the role ``agent`` to access the details of the authors who they manage in ``authors`` table. We can define the following permission rule that uses the aforementioned object relationship:
 
-.. thumbnail:: /img/graphql/manual/auth/nested-object-permission-simple-example.png
+.. thumbnail:: /img/graphql/core/auth/nested-object-permission-simple-example.png
 
 This permission rule reads as "*if the author's agent's*  ``id``  *is the same as the requesting user's* ``id`` *, allow access to the author's details*.
 
@@ -208,7 +208,7 @@ Column-level permissions
 ^^^^^^^^^^^^^^^^^^^^^^^^
 Column-level permissions determine access to columns in the rows that accessible based on row-level permissions. These permissions are simple selections: 
 
-.. thumbnail:: /img/graphql/manual/auth/column-level-permissions.png
+.. thumbnail:: /img/graphql/core/auth/column-level-permissions.png
 
 In this example, the role ``author`` has only partial access to columns of the accessible rows for the ``select`` operation.
 
@@ -219,7 +219,7 @@ Limiting number of rows
 
 In the case of ``select`` operations, the number of rows to be returned in the response can be limited using this configuration:
 
-.. thumbnail:: /img/graphql/manual/auth/limit-rows-for-select.png
+.. thumbnail:: /img/graphql/core/auth/limit-rows-for-select.png
 
 In the above example, this configuration  restricts the number of accessible rows (*based on the rule*: ``{"id":{"_eq":"X-Hasura-User-Id"}}``) to 20. 
 
@@ -230,7 +230,7 @@ Aggregation queries permissions
 
 In the case of ``select`` operations, access to :doc:`aggregation queries <../../queries/aggregation-queries>` can be restricted for a given role using this configuration.
 
-.. thumbnail:: /img/graphql/manual/auth/aggregation-query-permissions.png
+.. thumbnail:: /img/graphql/core/auth/aggregation-query-permissions.png
 
 In the above example, the role ``user`` is allowed to make aggregation queries.
 

docs/graphql/core/auth/authorization/role-multiple-rules.rst

@@ -53,7 +53,7 @@ Step 2: Create a relationship
 For the table ``user_info``, :ref:`create a manual object relationship <create_manual_relationships>` called
 ``private_info`` using ``user_info : id -> user_private : user_id``:
 
-.. thumbnail:: /img/graphql/manual/auth/multiple-rules-create-manual-relationship.png
+.. thumbnail:: /img/graphql/core/auth/multiple-rules-create-manual-relationship.png
    :alt: Create a manual object relationship
 
 Step 3: Define permissions
@@ -63,13 +63,13 @@ For the role ``user``, create the following permissions for ``select``:
 
 - Table ``user_info``: allow access to ``id``, ``name`` and ``city`` without any row conditions.
 
-.. thumbnail:: /img/graphql/manual/auth/multiple-rules-define-public-permissions.png
+.. thumbnail:: /img/graphql/core/auth/multiple-rules-define-public-permissions.png
    :alt: Column access for the role user
 
 - View ``user_private``: allow access to ``id``, ``phone``, ``email`` and ``address`` if the ``user-id``
   passed in the session variable is equal to the row's ``user_id``.
 
-.. thumbnail:: /img/graphql/manual/auth/multiple-rules-define-private-permissions.png
+.. thumbnail:: /img/graphql/core/auth/multiple-rules-define-private-permissions.png
    :alt: Column access for the role user based on row level permissions
 
 Step 4: Query with appropriate access control

docs/graphql/core/auth/authorization/roles-variables.rst

@@ -107,7 +107,7 @@ Roles are typically modelled in two ways:
 1. **Hierarchical roles**: Access scopes are nested depending on available roles. `Roles in Github for organisations <https://help.github.com/en/articles/managing-peoples-access-to-your-organization-with-roles>`_
    is a great example of such modelling where access scopes are inherited by deeper roles:
 
-   .. thumbnail:: /img/graphql/manual/auth/github-org-hierarchical-roles.png
+   .. thumbnail:: /img/graphql/core/auth/github-org-hierarchical-roles.png
       :alt: Hierarchical roles
 
 2. **Flat roles**: Non-hierarchical roles with each role requiring an independent access scope to be defined.

docs/graphql/core/auth/authorization/use-cases.rst.wip

@@ -18,7 +18,7 @@ Head to the ``Permissions`` tab of the ``author`` table.
 
 Now add a ``select`` access control rule for the ``user`` role on the ``author`` table:
 
-.. thumbnail:: /img/graphql/manual/auth/author-select-perms.png
+.. thumbnail:: /img/graphql/core/auth/author-select-perms.png
 
 This rule reads as:
 
@@ -44,7 +44,7 @@ This rule reads as:
 Now, let's make the same query as above but also include two dynamic authorization variables ``X-Hasura-Role`` and
 ``X-Hasura-User-Id`` via request headers. These will automatically get used according to the permission rule we set up.
 
-.. thumbnail:: /img/graphql/manual/auth/query-with-perms.png
+.. thumbnail:: /img/graphql/core/auth/query-with-perms.png
 
 You can notice above how the same query now only includes the right slice of data.
 
@@ -83,7 +83,7 @@ We can restrict the columns of a table that a particular role has access to.
 
 Head to the ``Permissions`` tab of the table and edit the ``Select`` permissions for the role:
 
-.. thumbnail:: /img/graphql/manual/auth/restrict-columns.png
+.. thumbnail:: /img/graphql/core/auth/restrict-columns.png
 
 .. _limit_rows:
 
@@ -94,7 +94,7 @@ We can set a hard limit on the maximum number of rows that will be returned in a
 
 Head to the ``Permissions`` tab of the table and edit the ``Select`` permissions for the role:
 
-.. thumbnail:: /img/graphql/manual/auth/limit-results.png
+.. thumbnail:: /img/graphql/core/auth/limit-results.png
 
 
 .. _using-relationships-in-permissions:
@@ -105,16 +105,16 @@ You can leverage relationships to define permission rules with fields from a nes
 
 * An author/articles schema where an article can have one or more reviewers i.e. users with the role ``reviewer`` can only edit those articles that have been assigned to them:
 
-.. thumbnail:: /img/graphql/manual/auth/schema-for-nested-object-based-permissions.png
+.. thumbnail:: /img/graphql/core/auth/schema-for-nested-object-based-permissions.png
 
 * The foreign key constraint from ``reviewers`` :: ``article_id``  →  ``articles`` :: ``id`` is used for an array relationship called  ``reviewers`` in the ``articles`` table:
 
-.. thumbnail:: /img/graphql/manual/auth/array-relationship-reviewers.png
+.. thumbnail:: /img/graphql/core/auth/array-relationship-reviewers.png
    :class: no-shadow
 
 We can use this relationship in a permission rule for the ``articles`` table  to limit access for users with the role ``reviewer`` to only assigned rows:
 
-.. thumbnail:: /img/graphql/manual/auth/nested-object-permissions-rule.gif
+.. thumbnail:: /img/graphql/core/auth/nested-object-permissions-rule.gif
 
 Via the relationship, we are using the ``reviewer_id`` field of the nested object ``reviewers`` in the the above permission rule that reads as "Allow updating an article if the **reviewer_id of any of the reviewers assigned to this article** is the same as the requesting user's id (*which is sent in the resolved session variable* ``X-Hasura-User-ID``)".
 
@@ -144,12 +144,12 @@ Let's say we have the following test data for the list of reviewers:
 
 Applying the above permission rule for "update" to "select" operation also, let's query the  ``articles`` table to watch this permission rule in action:
 
-.. thumbnail:: /img/graphql/manual/auth/restricted-data-for-role-reviewer.png
+.. thumbnail:: /img/graphql/core/auth/restricted-data-for-role-reviewer.png
   :class: no-shadow
 
 As we've made this query with the role ``reviewer`` and user ID ``5`` (*highlighted in the request headers in the above image*), we can only query those articles for which this user is a reviewer. This will be the case for update mutations too. As the user with id ``5`` does not have access to article with id ``2`` (*refer to the table above*), the following mutation will not update any rows of the ``articles`` table:
 
-.. thumbnail:: /img/graphql/manual/auth/unsuccessful-mutation-for-role-reviewer.png
+.. thumbnail:: /img/graphql/core/auth/unsuccessful-mutation-for-role-reviewer.png
   :class: no-shadow
    
 .. admonition:: Array and Object relationships work similarly

docs/graphql/core/auth/index.rst

@@ -15,7 +15,7 @@ Authentication & Authorization
 In Hasura, access control or authorization is based on **roles**. Let's take a look at how this works
 when the GraphQL engine receives a request:
 
-.. thumbnail:: /img/graphql/manual/auth/auth-high-level-overview.png
+.. thumbnail:: /img/graphql/core/auth/auth-high-level-overview.png
    :alt: Authentication and authorization with Hasura
 
 As you can see from this:

docs/graphql/core/business-logic/index.rst.wip

@@ -15,7 +15,7 @@ GraphQL engine/Postgres, different avenues are recommended for introducing such
 - **Post-CRUD**: :ref:`event-triggers`
 - :ref:`derived-data`
 
-.. thumbnail:: /img/graphql/manual/business-logic/custom-business-logic.png
+.. thumbnail:: /img/graphql/core/business-logic/custom-business-logic.png
 
 .. _remote-schemas:
 
@@ -35,7 +35,7 @@ To support these kinds of business logic, a custom GraphQL schema with resolvers
 logic is needed (*see link below for boilerplates*). This remote schema can then be merged with GraphQL engine's
 schema using the console. Here's a reference architecture diagram for such a setup:
 
-.. thumbnail:: /img/graphql/manual/schema/schema-stitching-v1-arch-diagram.png
+.. thumbnail:: /img/graphql/core/schema/schema-stitching-v1-arch-diagram.png
 
 For more details, links to boilerplates for custom GraphQL servers, etc. please head to :doc:`../remote-schemas/index`.
 
@@ -56,7 +56,7 @@ If your business logic is stateful, it can even store its state back in the Post
 with GraphQL engine, allowing your frontend app to offer a reactive user experience, where the app uses GraphQL
 subscriptions to listen to updates from your webhook via Postgres.
 
-.. thumbnail:: /img/graphql/manual/event-triggers/database-event-triggers.png
+.. thumbnail:: /img/graphql/core/event-triggers/database-event-triggers.png
 
 Event triggers are ideal for use cases such as the following:
 

docs/graphql/core/deployment/allow-list.rst

@@ -12,6 +12,9 @@ Allow-list of operations
   :depth: 1
   :local:
 
+Introduction
+------------
+
 The **Allow-list** is a list of safe operations (*GraphQL queries, mutations or subscriptions*) that is stored by
 the GraphQL engine in its metadata. When enabled, it can be used to restrict the GraphQL engine so that it
 executes **only** those operations that are present in the list *(available after version v1.0.0-beta.1)*.
@@ -42,7 +45,7 @@ You can add or remove a operation in the allow-list in two ways:
     to add multiple operations to the allow-list (each operation needs to have a name).
 
 * **Using metadata APIs:** Queries can be stored in collections and a collection can be added to or removed
-  from the allow-list. See :ref:`Collections & Allow-list APIs<api_query_collections>`
+  from the allow-list. See :ref:`Collections & Allow-list APIs <api_query_collections>`
   for API reference.
 
 .. note::