Hasura – Authentication

Handling authentication correctly is a key step in ensuring the security of your application in production. This is a very important component of any backend system. There are multiple ways to be authenticated but in this post I will focus on JWT authentication.

Ways to authenticate users for your application:

  1. JSON web tokens (JWT) based authentication: Use this method if you are authenticating your end-users using a JWT based authentication provider like Auth0 or Firebase or AWS Cognito.
  2. Webhook based authentication: Use this method if you need to roll out a custom authentication solution.
  3. Unauthenticated access: Use this method if you want to provide anonymous access to some data, for example if you want to make a public feed of events.
  4. Admin secret based authentication: Use this method if you are doing server to server communication and the client is a trusted client.


JWT based authentication

We assume you are familiar with what a JWT is. If you are new to JWT’s here is a guide we have put together explaining how JWT’s work in the context of front end GraphQL clients. It also covers the security aspects of using a JWT for authentication.

Here’s how JWT based authentication works:

  1. An end-user is authenticated to the app by your authentication server(sign up or sign in)
  2. On successful authentication, the authentication server returns a JWT to the app with the user and role information embedded in the claims section
  3. On subsequent calls to Hasura, app passes the JWT in the Authorization header.
  4. Hasura validates the token and extracts the user and role information

Validating the JWT Token in step 4. above requires a JWT secret. You can enable JWT mode by using the --jwt-secret flag or HASURA_GRAPHQL_JWT_SECRET environment variable while starting Hasura. The the value of the flag or environment variable must be a JSON object.


Note that key must be equal to or more than 32 characters.


JWT Payload

  "iss" : "folautech-api",
  "jti" : "5c16f712-7ded-4479-9c90-266501b003d0-PfAdAIEeLz",
  "sub" : "3",
  "aud" : "folautech-meal-plan",
  "iat" : "2021-03-16T09:02:12.955Z",
  "exp" : "2021-03-16T10:42:12.955Z",
  "admin" : false,
  "name" : "Laulau Kaveinga",
  "hasura" : {
    "x-hasura-default-role" : "user",
    "x-hasura-user-id" : "3",
    "x-hasura-allowed-roles" : [ "user" ]


  1. x-hasura-default-role field : indicating the default role of that user i.e. the role that will be used in case x-hasura-role header is not passed.
  2. x-hasura-allowed-roles field : a list of allowed roles for the user i.e. acceptable values of the x-hasura-role header. The x-hasura-default-role specified should be a member of this list.
  3. x-hasura-user-id field : id of the authenticated user which is used to authorized user to access database tables. 
  4. A x-hasura-custom field : you can add custom hasura properties which can be used to query database



Subscribe To Our Newsletter
You will receive our latest post and tutorial.
Thank you for subscribing!


Leave a Reply

Your email address will not be published. Required fields are marked *