Skip to main content
Version: v2.x

Auth0 JWT Integration with Hasura GraphQL Engine


This page helps you to set up Auth0 to work with the Hasura GraphQL Engine.

Create an Auth0 Application

  • Navigate to the Auth0 dashboard.
  • Click on the Applications menu option on the left, then click the + Create Application button.
  • In the Create Application window, set a name for your application, and select Single Page Web Applications. (assuming your application is React/Angular/Vue etc).
Create an Auth0 application

You get the basic information such as the Domain, Client ID, and Client Secret from the Applications > Settings tab once the application is created.

Configure Auth0 Rules & Callback URLs

In the Applications > Settings > Application URIs section, set Allowed Callback URLs to Select Save Changes.

Add domain-specific URLs as well for the production apps (e.g:


Disable the OIDC Conformant under Applications > Settings > Advanced Settings > OAuth section to avoid callback error.

Auth0 has multiple versions of its SDK that use different semantics to handle JWT.


Your client will not authenticate your app if a wrong token gets updated, as the necessary Hasura claims won't appear in the generated JWT.

In both cases, navigate to Auth Pipeline > Rules and create a rule here to add the custom JWT claims. You can choose any name for the rule.

For Auth0.js:

function (user, context, callback) {
const namespace = "";
context.idToken[namespace] =
'x-hasura-default-role': 'user',
// do some custom logic to decide allowed roles
'x-hasura-allowed-roles': ['user'],
'x-hasura-user-id': user.user_id
callback(null, user, context);

For auth0-spa-js:

function (user, context, callback) {
const namespace = "";
context.accessToken[namespace] =
'x-hasura-default-role': 'user',
// do some custom logic to decide allowed roles
'x-hasura-allowed-roles': ['user'],
'x-hasura-user-id': user.user_id
callback(null, user, context);

Create an Auth0 API

For auth0-spa-js, also create an API so that the access token issued by Auth0 follows the JWT standard. Read more about this here.

Navigate to Auth0 dashboard. Click on the APIs menu option on the left sidebar and click the + Create API button.

In the New API window, set a name for your API and enter an identifier (e.g. hasura). In your application code, configure your API identifier as the audience when initializing Auth0.

For example:

onRedirectCallback={() => ..}

You need to ensure that audience is set in the JWT. This can be done through appropriate client configuration or by setting the default audience in the tenant settings of Auth0.

Test auth0 login and generate sample JWTs for testing

You don't need to integrate your UI with Auth0 for testing. There are 2 ways you can test connections:

  1. If you are logged in to the Auth0 Dashboard:

    Navigate to Auth0 Dashboard, and select Authentication. Select the type of connection you want to test and select Try Connection.

  2. If you are not logged in to the Auth0 Dashboard:

    Use the Test partner connections embed link. Select LOG IN to login to your Auth0 domain.

    Select your application and copy the generated URL, like so:

    auth0 login
    1. client_id: Client ID of the application. This value is auto-filled from your application.
    2. connection: Name of the connection you want to test. Applications > <application_name> > Connections

    For example, to test the connection for Username-Password-Authentication, modify the above URL as:

    Once you follow the link, you will be redirected to your configured identity provider. After successful login, you will be sent back to to decode, verify and generate JWT.

    JWT debug on

    Save this JWT token value to be used later to test authorization using the Hasura Console.

Configure Hasura to use Auth0 Keys

Auth0 publishes their JWK under:


But they have a bug where the certificate thumbprint does not match. Hence, this URL does not work with Hasura.

The current workaround is to download the X590 certificate from:

https://<your-auth0-domain> and use it in the key field:

"key": "-----BEGIN CERTIFICATE-----

An easier way to generate the above config is to use the following UI:

You can use the generated config in the HASURA_GRAPHQL_JWT_SECRET env variable or --jwt-secret flag.

You can directly copy-paste the config in yaml files and command-line arguments as it takes care of escaping the new lines.

Generated JWT config

Add Access Control Rules via Hasura Console

Auth0 is configured and ready to be used in the application. You can now set up access control rules that are automatically applied whenever a client makes a GraphQL request with the Auth0 token.

Refer to Access control basics for more information.

Add an access control rule that uses x-hasura-user-id for the role user. Then make a GraphQL query or a mutation, with the authorization token from the previous step where we generated an Auth0 token.

JWT token used as bearer token on Hasura Console

You can also use the env variable HASURA_GRAPHQL_UNAUTHORIZED_ROLE or --unauthorized-role flag to set a role for unauthorized users (e.g. anonymous). This allows you to set permissions for users that are not logged in.

The configured unauthorized role is used whenever an access token is not present in a request to the GraphQL API.

This is useful for data that you would like anyone to be able to access and can be configured and restricted just like any other role.

Sync Users from Auth0

Now that you have created an Auth0 application and can sign up/login, you will need a way to sync your users in Postgres as well. All you need is the Auth0 user_id in something like a users table.

Using Auth0 Rules again, add the following rule which will insert a new user every time someone signs up.

function (user, context, callback) {
const userId = user.user_id;
const url = "";
const upsertUserQuery = `
mutation($userId: String!){
insert_users(objects: [{ id: $userId }], on_conflict: { constraint: users_pkey, update_columns: [] }) {
const graphqlReq = { "query": upsertUserQuery, "variables": { "userId": userId } }{
headers: {'content-type' : 'application/json', 'x-hasura-admin-secret': configuration.HASURA_ADMIN_SECRET},
url: url,
body: JSON.stringify(graphqlReq)
}, function(error, response, body){
callback(null, user, context);

Make sure to specify the HASURA_ADMIN_SECRET variable in the Rules > Settings section of Auth0.

That’s it! This rule will be triggered on every successful sign up/login and sync your Auth0 user into your postgres database.


We need to use an upsert operation here because social logins do not distinguish between sign-up and login. Hence, we need to run this rule every time a successful login is made and do nothing if the user already exists.

Local dev with Auth0 rules

The sync step will require a reachable endpoint to Hasura and this is not possible in localhost. You can use ngrok or similar services to expose your locally running Hasura with a public endpoint temporarily.

Additional Resources

Incorporate Auth0 with a full-stack application - Learn Tutorials.