Nhost

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:

• Email and Password
• Magic Link
• Phone Number (SMS)
• Google
• Facebook
• GitHub
• LinkedIn
• Spotify
• Discord
• Twitch

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.

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

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.

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.

Paste the Admin secret and press Enter

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

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

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.

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

Create users

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

We have created two users.

Now copy the User ID of the user you created.

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.

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

Copy
query {
  notes {
    id
    title
  }
}

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

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

Copy
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" }'

Copy
{"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.

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

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

Copy
Authorization: Bearer {JWT-token}

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.

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

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.

Copy
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" }'

Copy
{"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.

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:

• Next.js
• React
• RedwoodJS
• Vue