review edits

seanparkross · seanparkross · commit 7c74549783c1 · 2025-01-14T20:00:40.000Z
diff --git a/docs/auth/faq.mdx b/docs/auth/faq.mdx
@@ -12,8 +12,8 @@ keywords:
 
 ## Should I choose JWT or Webhook mode?
 
-JWT mode is the default mode and is recommended for most use cases. It's easy to set up, integrates with many 3rd party
-providers and provides a robust security model.
+JWT mode is recommended for most use cases. It's easy to set up, integrates with many 3rd party providers and provides a
+robust security model.
 
 Webhook mode is more flexible and can be useful for custom authentication scenarios. Webhook mode will be slightly
 slower than JWT mode due to the additional network request.
@@ -41,7 +41,8 @@ objects.
 
 ## How do I enable a fully open production API where any user can query anything without any auth in their queries?
 
-Use [NoAuth](/auth/noauth-mode.mdx) mode.
+Use [NoAuth](/auth/noauth-mode.mdx) mode and set the API to public via the console in Settings > Summary > API Access
+Mode or by using the `ddn project set-api-access-mode public` command.
 
 ## How do I enable a **mostly** fully public API with no authentication but where **some** fields are not public?
 
diff --git a/docs/auth/jwt/index.mdx b/docs/auth/jwt/index.mdx
@@ -33,11 +33,6 @@ In JWT mode, session variables are passed to the Hasura Engine on each request i
 - [Firebase JWT integration](/auth/jwt/tutorials/integrations/3-firebase.mdx)
 - [Clerk JWT integration](/auth/jwt/tutorials/integrations/4-clerk.mdx)
 
-- [JWT configuration information](/auth/jwt/jwt-configuration.mdx)
-
-## Integrations with 3rd party services
+## JWT configuration information
 
-- [Auth0 JWT integration](/auth/jwt/tutorials/integrations/1-auth0.mdx)
-- [AWS Cognito JWT integration](/auth/jwt/tutorials/integrations/2-aws-cognito.mdx)
-- [Firebase JWT integration](/auth/jwt/tutorials/integrations/3-firebase.mdx)
-- [Clerk JWT integration](/auth/jwt/tutorials/integrations/4-clerk.mdx)
+- [JWT configuration information](/auth/jwt/jwt-configuration.mdx)
diff --git a/docs/auth/jwt/jwt-configuration.mdx b/docs/auth/jwt/jwt-configuration.mdx
@@ -46,7 +46,7 @@ As a minimum, either the `type` **and** `key` values OR the `jwk_url` value **ha
 {
   "iat": 1735916718,
   "exp": 1796916677,
-  "https://hasura.io/jwt/claims": {
+  "claims.jwt.hasura.io": {
     "x-hasura-default-role": "user",
     "x-hasura-allowed-roles": ["user", "admin"],
     "x-hasura-user-id": "123",
@@ -73,7 +73,8 @@ of this example JWT token. The signature secret to verify this token with the HS
 The `x-hasura-role` value can be sent as a plain **header** in the request to indicate the role which should be used.
 
 When your auth server generates the JWT, the custom claims in the JWT **must contain the following** in a custom
-`https://hasura.io/jwt/claims` [namespace](#claims-namespace):
+namespace. This namespace can be any string you choose, as long as it matches the `claims_namespace` defined in your
+AuthConfig. Using `claims.jwt.hasura.io` will match our examples:
 
 1.  A `x-hasura-default-role` field. The role that will be used when the optional `x-hasura-role` _header_ is **not
     passed**.
@@ -236,7 +237,7 @@ The JWT token should be in the following format if the `claims_namespace_path` i
 :::info Claims namespace values
 
 The JWT config can only have one of either `claims_namespace` or `claims_namespace_path` values set. If neither keys are
-set, then the default value of `claims_namespace` i.e. `https://hasura.io/jwt/claims` will be used.
+set, then the default value of `claims_namespace` i.e. `claims.jwt.hasura.io` will be used.
 
 :::
 
@@ -261,7 +262,7 @@ If `claims_format` is `json` then the JWT claims should look like:
   "name": "John Doe",
   "admin": true,
   "iat": 1516239022,
-  "https://hasura.io/jwt/claims": {
+  "claims.jwt.hasura.io": {
     "x-hasura-allowed-roles": ["editor", "user", "mod"],
     "x-hasura-default-role": "user",
     "x-hasura-user-id": "1234567890",
@@ -279,7 +280,7 @@ If `claims_format` is `stringified_json` then the JWT claims should look like:
   "name": "John Doe",
   "admin": true,
   "iat": 1516239022,
-  "https://hasura.io/jwt/claims": "{\"x-hasura-allowed-roles\":[\"editor\",\"user\",\"mod\"],\"x-hasura-default-role\":\"user\",\"x-hasura-user-id\":\"1234567890\",\"x-hasura-org-id\":\"123\",\"x-hasura-custom\":\"custom-value\"}"
+  "claims.jwt.hasura.io": "{\"x-hasura-allowed-roles\":[\"editor\",\"user\",\"mod\"],\"x-hasura-default-role\":\"user\",\"x-hasura-user-id\":\"1234567890\",\"x-hasura-org-id\":\"123\",\"x-hasura-custom\":\"custom-value\"}"
 }
 ```
 
diff --git a/docs/auth/jwt/jwt-mode.mdx b/docs/auth/jwt/jwt-mode.mdx
@@ -46,7 +46,7 @@ used. If this is not provided, the engine will use the `x-hasura-default-role` v
 
 You can enable your Hasura DDN instance to use JWTs in just a few steps.
 
-## Step 1. Update your AuthConfig
+### Step 1. Update your AuthConfig
 
 Hasura utilizes an [AuthConfig](/supergraph-modeling/auth-config.mdx) object that allows you to define the configuration
 for your authentication service. In a standard setup the `auth-config.hml` file can be found in your `globals`
@@ -87,7 +87,7 @@ definition:
 
 Read more about other setup options [here](/supergraph-modeling/auth-config.mdx#authconfig-jwtconfig).
 
-## Step 2. Define the JWT with custom claims
+### Step 2. Define the JWT with custom claims
 
 Your auth service should include an object with a key of `claims.jwt.hasura.io` in the JWT. Within this, each claim
 should be prefixed with `x-hasura-*` and include the relevant information. Note that an extra optional `x-hasura-role`
@@ -133,11 +133,11 @@ vulnerability**. Learn how to set this [here](supergraph-modeling/auth-config.md
 
 :::
 
-## Step 3. Add permissions to an object in your supergraph
+### Step 3. Add permissions to an object in your supergraph
 
 {/* TODO: Add permissions to an object in your supergraph */}
 
-## Step 3. Rebuild your supergraph
+### Step 4. Rebuild your supergraph
 
 Once you've updated your `AuthConfig` object in `auth-config.hml` and updated your claims, you can rebuild your
 supergraph and test it locally.
@@ -146,7 +146,7 @@ supergraph and test it locally.
 ddn supergraph build local
 ```
 
-## Step 4. Make an authenticated request
+### Step 5. Make an authenticated request
 
 In the example above, we're using the `BearerAuthorization` method. As such, as we can make a request to our Hasura DDN
 instance by including a header with the key-value of `Authorization: Bearer <our-encoded-token>`. For testing, you can
diff --git a/docs/auth/overview.mdx b/docs/auth/overview.mdx
@@ -16,7 +16,6 @@ keywords:
   - data security
   - jwt mode
   - hasura integration
-hide_table_of_contents: true
 seoFrontMatterUpdated: true
 ---
 
diff --git a/docs/auth/permissions/command-permissions.mdx b/docs/auth/permissions/command-permissions.mdx
@@ -7,7 +7,7 @@ keywords:
   - role-based access
   - supergraph
   - argument presets
-sidebar_label: Command Permissions Guide
+sidebar_label: Command Permissions
 ---
 
 # Command Permissions
diff --git a/docs/auth/permissions/index.mdx b/docs/auth/permissions/index.mdx
@@ -21,9 +21,9 @@ user can access.
 
 The following types of permissions can be defined:
 
-- To define which **fields** are accessible by a role in the API, configure the appropriate
-  [`TypePermissions`](/auth/permissions/type-permissions.mdx)
 - To define what **data** within a model are allowed to be accessed by a role, configure the appropriate
   [`ModelPermissions`](/auth/permissions/model-permissions.mdx)
+- To define which **fields** are accessible by a role in the API, configure the appropriate
+  [`TypePermissions`](/auth/permissions/type-permissions.mdx)
 - To define whether the command is **executable** by a role, configure the appropriate
   [`CommandPermissions`](/auth/permissions/command-permissions.mdx)
diff --git a/docs/auth/permissions/model-permissions.mdx b/docs/auth/permissions/model-permissions.mdx
@@ -4,7 +4,7 @@ keywords:
   - model permissions
   - supergraph
   - data access control
-sidebar_position: 2
+sidebar_position: 1
 sidebar_label: Model Permissions
 ---
 
diff --git a/docs/auth/permissions/type-permissions.mdx b/docs/auth/permissions/type-permissions.mdx
@@ -1,5 +1,5 @@
 ---
-sidebar_position: 1
+sidebar_position: 2
 description: "Guide on defining Type Permissions for API fields in a supergraph."
 keywords:
   - type permissions
diff --git a/docs/auth/webhook/webhook-mode.mdx b/docs/auth/webhook/webhook-mode.mdx
@@ -23,15 +23,13 @@ import Thumbnail from "@site/src/components/Thumbnail";
 
 You can enable your Hasura DDN instance to use an auth webhook in just a few steps.
 
-This requires specifying a URL - which Hasura calls with the original request headers - that then returns a body
-containing the session variables after authenticating the request.
+You will need to provide a URL that Hasura will call with the original request headers, and it should return a body with
+the session variables after the request is authenticated.
 
 <Thumbnail src="/img/auth/auth-webhook-overview-diagram.png" alt="Authentication using webhooks" width="1000px" />
 
 ## Enabling Webhook authentication
 
-You can enable your Hasura DDN instance to use webhooks in just a few steps.
-
 ## Step 1. Update your AuthConfig {#update-authconfig}
 
 Hasura utilizes an [AuthConfig](/supergraph-modeling/auth-config.mdx) object that allows you to define the configuration
@@ -131,17 +129,15 @@ Content-Type: application/json
 
 {/* TODO: Write this section */}
 
-## Step 3. Rebuild your supergraph
-
-Once you've updated your `auth-config.hml`, you can rebuild your supergraph and test it locally.
+## Step 4. Rebuild your supergraph
 
 ```bash title="For example, from the root of your project, run:"
 ddn supergraph build local \
   --supergraph supergraph.yaml \
   --env-file .env
 ```
 
-## Step 4. Make an authenticated request
+## Step 5. Make an authenticated request
 
 In the example above, we're using the `BearerAuthorization` method. As such, as we can make a request to our Hasura DDN
 instance by including a header with the key-value of `Authorization: Bearer <our-encoded-token>`. For testing, you can
