Skip to main content
Version: v2.x

Quickstart

Let's see permissions in action by creating a simple example.

Step 1: Create a table

Head to your Console and create a table called users with the following database schema:

users (
id INT PRIMARY KEY,
name TEXT
)

Then, insert some sample data into the table using the Insert Row tab of the users table.

Step 2: Run a query without permissions

Head to the API tab in your Console and try out the below query:

query getUsers {
users {
id
name
}
}

The response of the above query contains all the users because, by default, the GraphQL query runs with admin permissions, giving access to all rows.

Run a query without access control

Step 3: Define permissions

Now let's define a permission for the users table for a role user.

Head to the Permissions section of the table in the Data -> [table] -> Permissions tab in the Console. Enter a new user role named user in the text input and define permissions for the select operation as:

Row permissions with custom check:

{
“id”: {
“_eq”: “X-Hasura-User-Id”
}
}

You can either write this out as text without the line breaks in the text area provided or use the builder interface to construct the rule.

Column permissions allow access:
✅ id
✅ name

The role will be created "on the fly" when you click the "Save Permissions" button.

Define access control rules

This permission rule reads as follows: "For the role user, in the table users and with operation select, allow access to those rows where the value in the id column is the same as the value in the X-Hasura-User-ID session variable, and allow access to the id and name columns".

Step 4: Run a query with permissions

Let's run the same query as before but now with the X-Hasura-Role and X-Hasura-User-ID session variables also included to indicate role and user information. These session variables are passed in the Request Headers section of GraphiQL as highlighted below:

Run a query with access control

As you can see, the results are now filtered based on the access control rule for the role user (since that is the role indicated by the X-Hasura-Role session variable) and the results are restricted to only those rows where the value in the id column is equal to 3 (as indicated by the X-Hasura-User-ID session variable).

As described in the Introduction section of the docs, your auth service is required to resolve these session variables.

Basics

To understand the basics of access control in Hasura, let's take a look at the parts of a SQL query:

Simple SQL query example

This query returns the right set of data by defining the requirements for the columns and rows in a given table.

Hasura's authorization rules work similarly - you define the permissions for a combination of table, user role and database operation (insert, update, select and delete).

Understanding access control in Hasura

In this example, only the columns, id, name and org_id and only the rows where the organization id of the user, org_id is equal to the supplied session permission X-Hasura-Org-Id value will be returned.

Hasura Engine uses both the database query itself and the permission rules to build one optimized query to the database. Which in this case would be something like:

SELECT id, name, org_id FROM users WHERE name LIKE '%john%' AND org_id = '1234';

Row-level permissions

Row-level permissions allow you to limit access to a subset of the rows in the table. These are essentially boolean expressions that, when evaluated against any particular row, determine access to it. They are constructed from the values in columns of the table, session variables and static values to build a boolean expression.

For example. The following row-level permission rule will restrict access to rows where the id column is equal to the x-hasura-user-id session variable of the request:

{
“id”: {
“_eq”: “X-Hasura-User-Id”
}
}

Column-level permissions

Column-level permissions allow you to limit access to only the columns you need for all the rows that are accessible based on the row level permission, as above.

Hasura column permissions

Other permissions

There are many more configuration options for permissions and data access besides the main ones of row and column. For details on all the permissions configuration options, see Configuring permission rules.

Next steps