What is Nhost?

Nhost is the open-source Firebase alternative with GraphQL and a development platform. Nhost is doing for the backend, what Netlify and Vercel are doing for the frontend. We provide a modern backend with the Postgres database, GraphQL API, Authentication, Storage, and Serverless Functions.

Nhost Authentication is a ready-to-use authentication service that is integrated with the GraphQL API and its permission system from Hasura. Nhost Authentication lets you authenticate users using different sign-in methods:

How it works

  1. When a user signs up, the user's information is inserted into the auth.users table in your database.
  2. Nhost returns an access token and a refresh token, together with the user's information.
  3. The user sends requests to Nhost services (GraphQL API, Authentication, Storage, Functions) with the access token as a header.
  4. The Nhost services use the user's access token to authorize the requests.

Nhost's authentication service is integrated with your database. All users are stored in the users table under the auth schema.

Create a Nhost project

If this is your first Nhost project, sign up using your GitHub or email. The next step is to create a Nhost project.


Click the Create Your First Project button to add project details.

Welcome to Nhost page

Give your new Nhost project a name, select a region and click Create Project.

New project page in Nhost console

A basic Notes app

For this guide, will be creating the backend for a notes app with two users. Each user will have a note with a unique id, title, body and details about when it was created or updated.

Nhost app dashboard

We now need to create a table named notes. The table will be created via Hasura Console. Click on Hasura from the Nhost panel. Copy the Admin Secret and click on Open Hasura.

The application's admin secret key

Paste the Admin secret and press Enter

Launching Hasura project

Head over to the Data tab and under the public schema of Databases, click on Create Table.

Hasura console

Enter table name, comment and column details as shown below.

Create a new table in Hasura

user_id will be our foreign key referencing the ID from the users table. If you delete a user, cascading will delete all the user's notes.

Set up foreign keys

Create permissions to read and write for the users role, to have role-specific access.

Table permissions for the user role

Table permissions for the user role

Create users

Go to the Auth section in the Nhost Dashboard and click on Add user to create users using email and password.

Add a new record in Nhost

We have created two users.

App records in Nhost

Now copy the User ID of the user you created.

Edit user details

Go over to the Database to access the notes table you created in Hasura. Add a new row using the user ID that you copied previously.

Notes table in Nhost

Insert a new row in Nhost

Similarly, add the other user's note by adding their user id.

Now head over to the Hasura console's GraphiQL playground, and uncheck the header x-hasura-admin-secret so that you can manage role-based access. Make GraphQL request to get all notes

query {
notes {

This query will fail because the user is not signed in while making the request.

Test app access

Make a curl command with the user's email and password in the terminal to sign in and receive the access token.

curl https://joprqixhifsgfwzrmxtp.auth.ap-south-1.nhost.run/v1/signin/email-password \
-v \
-H "Content-Type: application/json" \
-d '{ "email": "[email protected]", "password": "TestNhostApp@123" }'
{"session":{"accessToken":"eyJhbGciOiJIUzI1NiJ9.eyJodHRwczovL2hhc3VyYS5pby9qd3QvY2xhaW1zIjp7IngtaGFzdXJhLWFsbG93ZWQtcm9sZXMiOlsidXNlciIsIm1lIl0sIngtaGFzdXJhLWRlZmF1bHQtcm9sZSI6InVzZXIiLCJ4LWhhc3VyYS11c2VyLWlkIjoiZWM1OGNiZTgtZWI1Ny00NDM2LWFkMDktZjFmNDJmYjk1OGIzIiwieC1oYXN1cmEtdXNlci1pcy1hbm9ueW1vdXMiOiJmYWxzZSJ9LCJzdWIiOiJlYzU4Y2JlOC1lYjU3LTQ0MzYtYWQwOS1mMWY0MmZiOTU4YjMiLCJpYXQiOjE2NjI1MzQ3ODksImV4cCI6MTY2MjUzNTY4OSwiaXNzIjoiaGFzdXJhLWF1dGgifQ.vnJuBTc5kn-Vtuy7BzFlhvPpk4GwrZN_8syAu_ckCCM","accessTokenExpiresIn":900,"refreshToken":"cebaca26-6c51-42cc-a978-ae8702beb53e","user":{"id":"ec58cbe8-eb57-4436-ad09-f1f42fb958b3","createdAt":"2022-08-28T08:00:50.105078+00:00","displayName":"[email protected]","avatarUrl":"https://s.gravatar.com/avatar/0869e6d3ab4951a7262c3d680be4b680?r=g&default=blank","locale":"en","email":"[email protected]","isAnonymous":false,"defaultRole":"user","metadata":{},"emailVerified":true,"phoneNumber":null,"phoneNumberVerified":false,"activeMfaType":null,"roles":["user","me"]}},"mfa":null}%
<img width="1435" alt="Curl command for pratim" src="https://user-images.githubusercontent.com/32492961/188328581-f7101009-e376-4833-b9f6-608c345c2e26.png">

When a user signs in, they receive a JWT token that is used when making GraphQL requests. A JWT token consists of a header, payload and signature.

In the payload, you can see things like the user's id and default role.

The decoded JWT token

You can also decode your JWT token here and verify it using the NHOST_JWT_SECRET environment variable found in the settings.

The environment variables section in Nhost

Now add the JWT token in the headers inside GraphiQL like this and make the same query in the playground.

Authorization: Bearer {JWT-token}

Hasura console showing a query that retrieves all notes from the database

You can now see the user's details as you have been authenticated using Nhost Authentication and Hasura.

Let's try to retrieve Tom's note using the following query.

query {
notes(where: {id: {_eq: 2}}) {

Hasura console showing a query that retrieves a specific note from the database

The response is empty. Wonder why?

It is because we are trying to access Tom's details while we are logged in as Pratim. We previously defined permissions so that users can only read and write their notes. To access Tom's notes, we need to make the request using a JWT token issued to Tom.

We make the same curl command in our terminal with Tom's login details.

curl https://joprqixhifsgfwzrmxtp.auth.ap-south-1.nhost.run/v1/signin/email-password \
-v \
-H "Content-Type: application/json" \
-d '{ "email": "[email protected]", "password": "test@123" }'
{"session":{"accessToken":"eyJhbGciOiJIUzI1NiJ9.eyJodHRwczovL2hhc3VyYS5pby9qd3QvY2xhaW1zIjp7IngtaGFzdXJhLWFsbG93ZWQtcm9sZXMiOlsidXNlciIsIm1lIl0sIngtaGFzdXJhLWRlZmF1bHQtcm9sZSI6InVzZXIiLCJ4LWhhc3VyYS11c2VyLWlkIjoiNDU5ZmQ5NGMtZmIxNC00OWVjLWFkMjAtMjQ4YmJkMmJhOTQ0IiwieC1oYXN1cmEtdXNlci1pcy1hbm9ueW1vdXMiOiJmYWxzZSJ9LCJzdWIiOiI0NTlmZDk0Yy1mYjE0LTQ5ZWMtYWQyMC0yNDhiYmQyYmE5NDQiLCJpYXQiOjE2NjI1MzM1MjIsImV4cCI6MTY2MjUzNDQyMiwiaXNzIjoiaGFzdXJhLWF1dGgifQ.J-yCfxloyCvF0NCGvhferydft3NOJbL1q-wIgsxf-rI","accessTokenExpiresIn":900,"refreshToken":"f33bb87c-4ab0-4dbf-a352-5b04db246d7a","user":{"id":"459fd94c-fb14-49ec-ad20-248bbd2ba944","createdAt":"2022-09-04T16:25:32.641977+00:00","displayName":"[email protected]","avatarUrl":"https://s.gravatar.com/avatar/44e330dea0304e5f8005ef073510b2b1?r=g&default=blank","locale":"en","email":"[email protected]","isAnonymous":false,"defaultRole":"user","metadata":{},"emailVerified":false,"phoneNumber":null,"phoneNumberVerified":false,"activeMfaType":null,"roles":["user","me"]}},"mfa":null}%

You can now view Tom's note by adding the JWT token in the Authorization header and making the same query again.

Hasura console showing a query that retrieves all notes from the database

Now that you have your authentication and backend setup done, you can go ahead and build your frontend. You can get started with Nhost by following one of the quickstart guides:

Did you find this page helpful?
Start with GraphQL on Hasura for Free
  • ArrowBuild apps and APIs 10x faster
  • ArrowBuilt-in authorization and caching
  • Arrow8x more performant than hand-rolled APIs
footer illustration
Brand logo
© 2024 Hasura Inc. All rights reserved