Configuring permission rules¶

Using column operators to build rules¶

Type-based operators (depending on the column type) are available for constructing row-level permissions. You can use the same operators that you use to filter query results along with a few others to define permission rules.

See the API reference for a list of all supported column operators.

For example, the following two images illustrate the different operators available for integer and text types:

Using boolean expressions¶

The following is an example of a simple boolean expression to restrict access for select to rows where the value in the id column is greater than 10:

Console

CLI

API

You can define permissions using boolean expressions on the Hasura console as follows:

You can define permissions using boolean expressions in the tables.yaml file inside the metadata directory:

   - table:
       schema: public
       name: author
     select_permissions:
     - role: user
       permission:
         columns: []
         filter:
           id:
             _gt: 10

Apply the metadata by running:

hasura metadata apply

You can define permissions using boolean expressions when using the permissions metadata API:

POST /v1/query HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin

{
   "type": "create_select_permission",
   "args": {
      "table": "author",
      "role": "user",
      "permission": {
         "columns": "*",
         "filter": {
            "id": {"_gt": 10}
         }
      }
   }
}

You can construct more complex boolean expressions using the _and, _or and not operators:

For example, using the _and operator, you can construct a rule to restrict access for select to rows where the value in the id column is greater than 10 and the value in the name column starts with “a” or “A”:

Console

CLI

API

You can define permissions using the _and operator on the Hasura console as follows:

You can define permissions using the _and operator in the tables.yaml file inside the metadata directory:

   - table:
       schema: public
       name: author
     select_permissions:
     - role: user
       permission:
         columns: []
         filter:
           _and:
             - id: {_gt: 10}
             - name: {_ilike: a%}

Apply the metadata by running:

hasura metadata apply

You can define permissions using the _and operator when using the permissions metadata API:

POST /v1/query HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin

{
   "type": "create_select_permission",
   "args": {
      "table": "author",
      "role": "user",
      "permission": {
         "columns": "*",
         "filter": {
            "$and": [
               {
                  "id": {
                     "_gt": 10
                  }
               },
               {
                  "name": {
                     "_ilike": "a%"
                  }
               }
            ]
         }
      }
   }
}

Using session variables¶

Session variables that have been resolved from authentication tokens by either your authentication webhook or by Hasura using the JWT configuration are available for constructing row-level permissions.

For example, to allow an author to access only their articles, you can use the X-Hasura-User-ID session variable to construct a rule to restrict access for select to rows in the articles table where the value in the id column is equal to the value in the session variable (assuming this variable is being used to indicate the author’s ID):

Console

CLI

API

You can define session variables in permissions on the Hasura console:

You can define session variables in permissions in the tables.yaml file inside the metadata directory:

   - table:
       schema: public
       name: article
     select_permissions:
     - role: author
       permission:
         columns:
         - title
         - content
         filter:
           id:
             _eq: X-Hasura-User-Id

Apply the metadata by running:

hasura metadata apply

You can define session variables in permissions tables when using the permissions metadata API:

POST /v1/query HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin

{
   "type": "create_select_permission",
   "args": {
      "table": "article",
      "role": "author",
      "permission": {
         "columns": "*",
         "filter": {
            "id": "X-Hasura-User-Id"
         }
      }
   }
}

Using relationships or nested objects¶

You can leverage table relationships to define permission rules with fields from a nested object.

For example, let’s say you have an object relationship called agent from the authors table to another table called agent (an author can have an agent) and we want to allow users with the role agent to access the details of the authors who they manage in authors table. We can define the following permission rule that uses the aforementioned object relationship:

Console

CLI

API

You can use a nested object to build rules on the Hasura console:

You add permissions using relationships or nested objects in the tables.yaml file inside the metadata directory:

   - table:
       schema: public
       name: author
     select_permissions:
     - role: agent
       permission:
         columns: []
         filter:
           agent:
             agent_id:
               _eq: X-Hasura-User-Id

Apply the metadata by running:

hasura metadata apply

You add permissions using relationships or nested objects when using the permissions metadata API:

POST /v1/query HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin

   {
      "type": "create_select_permission",
      "args": {
         "table": "author",
         "role": "agent",
         "permission": {
            "columns": "*",
            "filter": {
               "agent": {
                  "agent_id": {
                     "_eq": "X-Hasura-User-Id"
                  }
               }
            }
         }
      }
   }

This permission rule reads as “if the author’s agent’s id is the same as the requesting user’s id , allow access to the author’s details.”

Using unrelated tables / views¶

You can use the _exists operator to set a permission rule based on tables/views that are not related to our table.

For example, say we want to allow a user to insert an article only if the value of the allow_article_create column in the users table is set to true. Let’s assume the user’s id is passed in the X-Hasura-User-ID session variable.

Console

CLI

API

You can set permissions using unrelated tables on the Hasura console as follows:

You can set permissions using unrelated tables in the tables.yaml file inside the metadata directory:

   - table:
       schema: public
       name: article
     insert_permissions:
     - role: user
       permission:
         check:
           _exists:
             _where:
               _and:
                 - id: {_eq: X-Hasura-User-Id}
                 - allow_article_create: {_eq: true}
             _table:
               schema: public
               name: users
         columns:
         - content
         - id
         - title

Apply the metadata by running:

hasura metadata apply

You can set permissions for unrelated tables when using the permissions metadata API:

POST /v1/query HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin

{
   "type": "create_insert_permission",
   "args": {
      "table": "article",
      "role": "user",
      "permission": {
         "columns": "*",
         "check": {
            "$exists": {
               "_table": "users",
               "_where": {
                  "$and": [
                     {
                        "id": "X-Hasura-User-Id"
                     },
                     {
                        "allow_article_create": true
                     }
                  ]
               }
            }
         }
      }
   }
}

This permission rule reads as “if there exists a row in the table users whose id is the same as the requesting user’s id and has the allow_article_create column set to true, allow access to insert articles.”