Skip to content

Parse for Hasura vs PromptQL Language #118

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
wants to merge 15 commits into
base: main
Choose a base branch
from
4 changes: 2 additions & 2 deletions docs/_prereqs.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -19,8 +19,8 @@ To use this guide, ensure you've installed/updated your CLI to at least `v2.28.0

**Install [Docker](https://docs.docker.com/engine/install/)**

The Docker-based workflow helps you iterate and develop locally without deploying any changes to Hasura DDN, making the
development experience faster and your feedback loops shorter. **You'll need Docker Compose `v2.20` or later.**
The Docker-based workflow helps you iterate and develop locally without deploying any changes to PromptQL Cloud, making
the development experience faster and your feedback loops shorter. **You'll need Docker Compose `v2.20` or later.**

**Validate the installation**

Expand Down
13 changes: 6 additions & 7 deletions docs/_quickstart_template.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -2,12 +2,12 @@ import Thumbnail from "@site/src/components/Thumbnail";

### Step 1. Authenticate your CLI

```ddn title="Before you can create a new Hasura DDN project, you need to authenticate your CLI:"
```ddn title="Before you can create a new project, you need to authenticate your CLI:"
ddn auth login
```

This will launch a browser window prompting you to log in or sign up for Hasura Cloud. After you log in, the CLI will
acknowledge your login, giving you access to Hasura Cloud resources.
This will launch a browser window prompting you to log in or sign up for PromptQL Cloud. After you log in, the CLI will
acknowledge your login, giving you access to PromptQL Cloud resources.

### Step 2. Scaffold out a new local project

Expand Down Expand Up @@ -70,7 +70,7 @@ The build is stored as a set of JSON files in `engine/build`.

### Step 7. Start your local services

```ddn title="Start your local Hasura DDN Engine and PostgreSQL connector:"
```ddn title="Start your local engine and PostgreSQL connector:"
ddn run docker-start
```

Expand All @@ -87,8 +87,7 @@ ddn console --local
### Step 2. Ask questions about your dataset

The console is a web app hosted at [`promptql.console.hasura.io`](https://promptql.console.hasura.io) that connects to
your local PromptQL API and data sources. Your data is processed in the DDN PromptQL runtime but isn't persisted
externally.
your local project API with data sources. Your data is processed in the PromptQL runtime but isn't persisted externally.

Head over to the console and ask a few questions about your data.

Expand Down Expand Up @@ -194,7 +193,7 @@ ddn run docker-start

### Step 2. Approve an action

```plaintext title="From the PromptQL playground, ask the following question:"
```plaintext title="From the PromptQL Playground, ask the following question:"
I really like Apollo 13; can you recommend a single movie with the same actors that is a historical story?
```

Expand Down
2 changes: 1 addition & 1 deletion docs/auth/faq.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ description: "Frequently Asked Questions about authentication modes and permissi
keywords:
- JWT mode
- Webhook mode
- Hasura permissions
- permissions
- NoAuth mode
---

Expand Down
6 changes: 3 additions & 3 deletions docs/auth/jwt/index.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -2,8 +2,8 @@
sidebar_position: 1
sidebar_label: JWT
description:
"Explore how Hasura supports JWT authentication for your GraphQL API, including setup, configuration, and integration
with third-party services like Auth0, AWS Cognito, Firebase, and Clerk."
"Explore how PromptQL supports JWT authentication for your GraphQL API, including setup, configuration, and
integration with third-party services like Auth0, AWS Cognito, Firebase, and Clerk."
keywords:
- jwt
- hasura
Expand All @@ -19,7 +19,7 @@ keywords:

# JWT Mode

In JWT mode, session variables are passed to the Hasura Engine on each request in JSON Web Tokens (JWTs).
In JWT mode, session variables are passed to the engine on each request in JSON Web Tokens (JWTs).
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Without more context from the page, my advice here is to be a bit more abstract:

Suggested change
In JWT mode, session variables are passed to the engine on each request in JSON Web Tokens (JWTs).
In JWT mode, session variables are passed to your application on each request in JSON Web Tokens (JWTs).

Copy link
Contributor Author

@seanparkross seanparkross May 29, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think this is too abstract as it doesn't have enough useful meaning.


## JWT mode setup

Expand Down
70 changes: 35 additions & 35 deletions docs/auth/jwt/jwt-configuration.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -73,7 +73,7 @@ eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3MzU5MTY3MTgsImV4cCI6MTc5NjkxNjY
of this example JWT token. The signature secret to verify this token with the HS256 algorithm is
`ultra-secret-very-secret-super-secret-key`.

## Hasura JWT format
## JWT format

The `x-hasura-role` value can be sent as a plain **header** in the request to indicate the role which should be used.

Expand All @@ -88,7 +88,7 @@ AuthConfig. Using `claims.jwt.hasura.io` will match our examples.
3. Add any other optional `x-hasura-*` claim fields (required as per your defined permissions) to the custom namespace.

To summarize, `x-hasura-allowed-roles` session variable contains a list of all the roles that the user can assume and
the `x-hasura-role` header tells the Hasura Engine which role to use for the request, and if that is missing then the
the `x-hasura-role` header tells the engine which role to use for the request, and if that is missing then the
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Similar to what we said earlier, in this context, I think we replaced Hasura engine with API. Why?

In context, we're referring to the behavior of the interface that receives and processes requests (the engine), which is equivalent to an API server.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This also isn't "correct enough" in my view. It isn't the API, (which is the endpoints, protocol and format) - it's the engine which uses them.

`x-hasura-default-role` session variable will be used.

This setup makes it more convenient for a JWT to only need to be issued once with a list of allowed roles for the user,
Expand All @@ -99,10 +99,10 @@ If, for example, your app will not need to switch user roles and the user only n
can just issue a JWT with `x-hasura-default-role` set to `user` and `x-hasura-allowed-roles` set to `["user"]` and not
send the `x-hasura-role` header in the request.

This setup is designed so that there is one authoritative way to construct your JWT token for the Hasura Engine which
can cover a wide range of use cases.
This setup is designed so that there is one authoritative way to construct your JWT token for the engine which can cover
a wide range of use cases.

## Hasura JWT Claim Description
## JWT Claim Description

### x-hasura-default-role

Expand All @@ -114,7 +114,7 @@ the header of the request. Usually, this will be the role with the least privile

The `x-hasura-allowed-roles` list can contain all the roles which a particular user can assume, eg:
`[ "user", "manager", "owner" ]`. Usually, these will have varying degrees of access to your data as specified in
Permissions and by specifying this list it lets the Hasura Engine know that this user can assume any of them.
Permissions and by specifying this list it lets the engine know that this user can assume any of them.

### x-hasura-\*

Expand All @@ -127,11 +127,11 @@ your auth provider.
## JWT Notes

- JWT claim fields eg: `x-hasura-default-role` are case-insensitive.
- Hasura Engine only has access to headers and JWT claims which are prefixed with `x-hasura-`.
- Hasura Engine only has access to JWT claims in namespace defined in the `AuthConfig` object in metadata.
- The engine only has access to headers and JWT claims which are prefixed with `x-hasura-`.
- The engine only has access to JWT claims in namespace defined in the `AuthConfig` object in metadata.
- All `x-hasura-*` values should be of type `String`, they will be converted to the right type automatically.

## Hasura JWT configuration options
## JWT configuration options

### claimsConfig

Expand All @@ -140,8 +140,8 @@ You can specify where the engine should look for the claims within the decoded t

#### namespace {#jwt-claims-config-namespace}

The `namespace` option is used when all of the Hasura claims are present in a single object within the decoded JWT. Our
example uses `claims.jwt.hasura.io` in the [Example Decoded Payload](#example-decoded-payload).
The `namespace` option is used when all of the PromptQL claims are present in a single object within the decoded JWT.
Our example uses `claims.jwt.hasura.io` in the [Example Decoded Payload](#example-decoded-payload).

```yaml
claimsConfig:
Expand All @@ -153,7 +153,7 @@ claimsConfig:
The `location` field indicates the location of the namespace object that uses
[RFC 6901 JSON Pointer](https://datatracker.ietf.org/doc/html/rfc6901) string syntax.

The `claimsFormat` field indicates whether the Hasura-specific claims are a regular JSON object or a stringified JSON.
The `claimsFormat` field indicates whether the PromptQL-specific claims are a regular JSON object or a stringified JSON.
The following possible values are allowed: `Json`, `StringifiedJson`.

This is required because providers like AWS Cognito only allow strings in the JWT claims.
Expand Down Expand Up @@ -193,8 +193,8 @@ If `claimsFormat` is `StringifiedJson` then the JWT claims should look like:

#### locations {#jwt-claims-config-locations}

This `locations` option can be used when Hasura claims are not all present in the single object, but individual claims
are provided a JSON pointer within the decoded JWT. In this option, you can indicate:
This `locations` option can be used when DDN claims are not all present in the single object, but individual claims are
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Earlier, we called this PromptQL claims (line 143).

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🤷‍♂️ Dunno on this one.

provided a JSON pointer within the decoded JWT. In this option, you can indicate:

- a literal value.
- or a JSON pointer path for individual claims and an optional default value if the claim doesn't exist.
Expand Down Expand Up @@ -309,7 +309,7 @@ The following are the possible values:

#### BearerAuthorization

In this mode, Hasura expects an `Authorization` header with a `Bearer` token.
In this mode, the engine expects an `Authorization` header with a `Bearer` token.

```yaml
tokenLocation:
Expand All @@ -324,8 +324,8 @@ Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWI...

#### Cookie

In the cookie mode, Hasura will try to parse the cookie header with the given cookie name. The value of the cookie
should be the exact JWT.
In the cookie mode, the DDN engine will try to parse the cookie header with the given cookie name. The value of the
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why would we make this different from the previous change on line 312?

In this mode, the engine expects an `Authorization` header with a `Bearer` token.

cookie should be the exact JWT.

```yaml
tokenLocation:
Expand All @@ -341,7 +341,7 @@ Cookie: cookie_name=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWI...

#### Header

In the custom header mode, Hasura expects a `header_name` header with the exact JWT token value.
In the custom header mode, the DDN engine expects a `header_name` header with the exact JWT token value.

```yaml
tokenLocation:
Expand Down Expand Up @@ -402,7 +402,7 @@ key:
The JWTs must be signed by the JWK published at the given URL. They can be signed by any algorithm that is compatible
with the key (eg. `RS256`, `RS384`, `RS512` algorithms require a JWK with an RSA key).

Hasura DDN does not currently support rotating JWKs.
The engine does not currently support rotating JWKs.

### audience

Expand Down Expand Up @@ -440,8 +440,8 @@ definition:
:::danger Audience Security Vulnerability

Certain JWT providers share JWKs between multiple tenants. They use the `aud` claim of the JWT to specify the intended
audience. Setting the `audience` field in the Hasura JWT configuration will make sure that the `aud` claim from the JWT
is also checked during verification. Not doing this check will allow JWTs issued for other tenants to be valid as well.
audience. Setting the `audience` field in the DDN JWT configuration will make sure that the `aud` claim from the JWT is
also checked during verification. Not doing this check will allow JWTs issued for other tenants to be valid as well.

In these cases, you **MUST** set the `audience` field to the appropriate value. Failing to do so is a **major security
vulnerability**.
Expand Down Expand Up @@ -482,7 +482,7 @@ definition:
`allowedSkew` is an optional field to provide some leeway (to account for clock skews) while comparing the JWT expiry
time. This field expects an integer value which will be the number of seconds of the skew value.

### Hasura JWT Config Examples
### JWT Config Examples

#### HMAC-SHA based

Expand All @@ -508,7 +508,7 @@ definition:
value: 3EK6FD+o0+c7tzBNVfjpMkNDi2yARAAKzQlk8O2IKoxQu4nF7EdAh8s3TwpHwrdWT6R
```

The `key` is the actual shared secret, which is used by Hasura and the external auth server.
The `key` is the actual shared secret, which is used by the engine and the external auth server.

#### RSA based

Expand Down Expand Up @@ -709,17 +709,17 @@ definition:
### Setting audience check

Certain JWT providers share JWKs between multiple tenants (like Firebase). They use the `aud` claim of JWT to specify
the intended tenant for the JWT. Setting the `audience` field in the Hasura JWT configuration will make sure that the
`aud` claim from the JWT is also checked during verification. Not doing this check will allow JWTs issued for other
tenants to be valid as well.
the intended tenant for the JWT. Setting the `audience` field in the JWT configuration will make sure that the `aud`
claim from the JWT is also checked during verification. Not doing this check will allow JWTs issued for other tenants to
be valid as well.

In these cases, you **MUST** set the `audience` field to appropriate value. **Failing to do so is a major security
vulnerability**.

## JWT with the WebSocket protocol

When executing a subscription (or query or mutation) over the WebSocket protocol, the authentication step is executed on
`connection_init` when the websocket is connected to Hasura Engine and is valid until the expiry of the JWT when in JWT
`connection_init` when the websocket is connected to the engine and is valid until the expiry of the JWT when in JWT
mode.

Once authenticated, all operations are allowed without further check, until the authentication expires.
Expand All @@ -737,16 +737,16 @@ This is a known issue and is documented by AWS in
> Standard libraries are not compatible with the padding that is included in the Application Load Balancer
> authentication token in JWT format.

Currently, there is no workaround possible in Hasura. Even if Hasura strips the additional padding the signature
verification of the token would fail (as Hasura had to tamper the token).
Currently, there is no workaround possible. Even if the engine strips the additional padding the signature verification
of the token would fail (as we had to tamper the token).

### Firebase

Firebase publishes the JWKs at:

[https://www.googleapis.com/service_accounts/v1/jwk/[email protected]](https://www.googleapis.com/service_accounts/v1/jwk/[email protected])

If you are using Firebase and Hasura, use this config:
If you are using Firebase and PromptQL, use this config:

```yaml
kind: AuthConfig
Expand All @@ -770,18 +770,18 @@ definition:
### Auth0 {#auth0-issues}

Refer to the [Auth0 JWT tutorial](/auth/jwt/tutorials/integrations/1-auth0.mdx) for a detailed guide on integrating
Auth0 with Hasura.
Auth0 with your project.

### Clerk

Clerk integrates with Hasura DDN using JWTs.
Clerk integrates with your project using JWTs.

Clerk publishes their JWK under: `https://<YOUR_CLERK_FRONTEND_API>/.well-known/jwks.json`

Refer to the [Clerk JWT tutorial](/auth/jwt/tutorials/integrations/4-clerk.mdx) to set up authenticated requests to
Hasura with Clerk.
Refer to the [Clerk JWT tutorial](/auth/jwt/tutorials/integrations/4-clerk.mdx) to set up authenticated requests to your
project with Clerk.

### Keycloak

By default, Keycloak uses the `RSA-OAEP` algorithm, which Hasura doesn't support. Remove the algorithm in the
By default, Keycloak uses the `RSA-OAEP` algorithm, which the engine doesn't support. Remove the algorithm in the
`Realm Settings -> Keys -> Add Providers` tab.
32 changes: 16 additions & 16 deletions docs/auth/jwt/jwt-mode.mdx
Original file line number Diff line number Diff line change
@@ -1,10 +1,10 @@
---
description:
"Learn how to configure JWT authentication in Hasura, including setting up AuthConfig, defining custom claims, and
"Learn how to configure JWT authentication in PromptQL, including setting up AuthConfig, defining custom claims, and
making authenticated requests."
keywords:
- JWT authentication
- Hasura
- PromptQL
- AuthConfig
- JSON Web Token
- supergraph
Expand All @@ -21,8 +21,8 @@ import Thumbnail from "@site/src/components/Thumbnail";
JWT mode requires that the client making the request sends a valid JSON Web Token to application. This JWT is provided
by an auth service such as Auth0, AWS Cognito, Firebase, Clerk, or your own custom solution.

Hasura then verifies and decodes the JWT to extract `x-hasura-*` session variable claim values from a defined namespace
in the token.
The engine then verifies and decodes the JWT to extract `x-hasura-*` session variable claim values from a defined
namespace in the token.

The `x-hasura-default-role` and `x-hasura-allowed-roles` session variables are required, and you will also most likely
utilize the user id and any other information which you need to determine access to your data.
Expand Down Expand Up @@ -53,16 +53,16 @@ You can enable your application to use JWTs in just a few steps.

### Step 1. Update your AuthConfig

Hasura utilizes an [AuthConfig](/reference/metadata-reference/auth-config.mdx) object that allows you to define the
PromptQL utilizes an [AuthConfig](/reference/metadata-reference/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` directory.

:::tip Hasura VS Code extension
:::tip VS Code extension

You can use [Hasura's VS Code extension](https://marketplace.visualstudio.com/items?itemName=HasuraHQ.hasura) to
scaffold out your `AuthConfig` object by typing `AuthConfig` and selecting this object from the list of available
options. As you navigate through the skeleton, you can type `CTRL+SPACEBAR` at any point to reveal options for the
different key-value pairs.
You can use [VS Code extension](https://marketplace.visualstudio.com/items?itemName=HasuraHQ.hasura) to scaffold out
your `AuthConfig` object by typing `AuthConfig` and selecting this object from the list of available options. As you
navigate through the skeleton, you can type `CTRL+SPACEBAR` at any point to reveal options for the different key-value
pairs.

:::

Expand Down Expand Up @@ -129,9 +129,9 @@ The signature secret to verify this token with the HS256 algorithm is `ultra-sec
:::warning Setting audience check

Certain JWT providers (like Firebase) share JWKs between multiple tenants. They use the `aud` claim of JWT to specify
the intended tenant for the JWT. Setting the `audience` field in the Hasura JWT configuration will make sure that the
`aud` claim from the JWT is also checked during verification. Not doing this check will allow JWTs issued for other
tenants to be valid as well.
the intended tenant for the JWT. Setting the `audience` field in the JWT configuration will make sure that the `aud`
claim from the JWT is also checked during verification. Not doing this check will allow JWTs issued for other tenants to
be valid as well.

In these cases, you **MUST** set the `audience` field to appropriate value. **Failing to do so is a major security
vulnerability**. Learn how to set this [here](reference/metadata-reference/auth-config.mdx#authconfig-jwtconfig).
Expand Down Expand Up @@ -234,9 +234,9 @@ ddn supergraph build local

### 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
pass this value in via the [PromptQL Playground client](/auth/playground-auth.mdx).
In the example above, we're using the `BearerAuthorization` method. As such, as we can make a request to our project by
including a header with the key-value of `Authorization: Bearer <our-encoded-token>`. For testing, you can pass this
value in via the [PromptQL Playground client](/auth/playground-auth.mdx).

## Next steps

Expand Down
2 changes: 1 addition & 1 deletion docs/auth/jwt/tutorials/index.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ seoFrontMatterUpdated: false
## Introduction

In this section of tutorials, we'll provide you with concise up-to-date descriptions of how to connect your preferred
authentication provider to Hasura DDN.
authentication provider to your project.

## Tutorials

Expand Down
Loading
Loading