Schema/Metadata API Reference: Permissions¶
Table of contents
Introduction¶
The permission layer is designed to restrict the operations that can be
performed by various users. Permissions can be defined on various operations
(insert/select/update/delete) at a role level granularity. By default, the admin
role has unrestricted access to all operations.
Variables in rules
All X-Hasura-*
header values can be used in the permission rules. These
values can come with the request and can be validated using webhook or can be
sent with the JWT token.
create_insert_permission¶
An insert permission is used to enforce constraints on the data that is being inserted.
Let’s look at an example, a permission for the user
role to insert into the
article
table. What is the constraint that we would like to enforce here? A
user can only insert articles for themselves .
POST /v1/query HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin
{
"type" : "create_insert_permission",
"args" : {
"table" : "article",
"role" : "user",
"permission" : {
"check" : {
"author_id" : "X-HASURA-USER-ID"
},
"set":{
"id":"X-HASURA-USER-ID"
},
"columns":["name","author_id"]
}
}
}
This reads as follows - for the user
role:
- For every row that is being inserted into the article table, allow insert only if the
check
passes i.e. that theauthor_id
column value is the same as the value in the request headerX-HASURA-USER-ID
”. - If the above
check
passes, then access for insert will be limited to columnsname
andauthor_id
only. - When this insert happens, the value of the column
id
will be automaticallyset
to the value of the resolved session variableX-HASURA-USER-ID
.
The argument for check
is a boolean expression which has the same syntax as the where
clause in the select
query, making it extremely expressive.
An example:
POST /v1/query HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin
{
"type" : "create_insert_permission",
"args" : {
"table" : "article",
"role" : "user",
"permission" : {
"check" : {
"author_id" : "X-HASURA-USER-ID",
"$or" : [
{
"category" : "editorial",
"is_reviewed" : false
},
{
"category" : { "$neq" : "editorial"}
}
]
}
}
}
}
In the above definition, the row is allowed to be inserted if the author_id
is the same as the request’s user id and is_reviewed
is false
when the
category
is “editorial”.
Args syntax¶
Key | Required | Schema | Description |
---|---|---|---|
table | true | TableName | Name of the table |
role | true | RoleName | Role |
permission | true | InsertPermission | The permission definition |
comment | false | text | Comment |
InsertPermission¶
Key | Required | Schema | Description |
---|---|---|---|
check | true | BoolExp | This expression has to hold true for every new row that is inserted |
set | false | ColumnPresetsExp | Preset values for columns that can be sourced from session variables or static values |
columns | false | PGColumn array (or) '*' |
Can insert into only these columns (or all when '*' is specified) |
backend_only | false | Boolean | When set to true the mutation is accessible only if x-hasura-use-backend-only-permissions
session variable exists and is set to true and request is made with x-hasura-admin-secret
set if any auth is configured |
drop_insert_permission¶
The drop_insert_permission
API is used to drop an existing insert permission for a role on a table.
An example:
POST /v1/query HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin
{
"type" : "drop_insert_permission",
"args" : {
"table" : "article",
"role" : "user"
}
}
create_select_permission¶
A select permission is used to restrict access to only the specified columns and rows.
Let’s look at an example, a permission for the user
role to select from the
article
table: all columns can be read, as well as the rows that have been published or
authored by the user themselves.
POST /v1/query HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin
{
"type" : "create_select_permission",
"args" : {
"table" : "article",
"role" : "user",
"permission" : {
"columns" : "*",
"filter" : {
"$or" : [
{ "author_id" : "X-HASURA-USER-ID" },
{ "is_published" : true }
]
},
"limit": 10,
"allow_aggregations": true
}
}
}
This reads as follows - For the user
role:
- Allow selecting rows where the
check
passes i.e.is_published
istrue
or theauthor_id
matches the value of the session variableX-HASURA-USER-ID
. - Allow selecting all columns (because the
columns
key is set to*
). limit
the numbers of rows returned by a query to thearticle
table by theuser
role to a maximum of 10.- Allow aggregate queries.
Args syntax¶
Key | Required | Schema | Description |
---|---|---|---|
table | true | TableName | Name of the table |
role | true | RoleName | Role |
permission | true | SelectPermission | The permission definition |
comment | false | text | Comment |
SelectPermission¶
Key | Required | Schema | Description |
---|---|---|---|
columns | true | PGColumn array (or) '*' |
Only these columns are selectable (or all when '*' is specified) |
computed_fields | false | ComputedFieldName array | Only these computed fields are selectable |
filter | true | BoolExp | Only the rows where this expression holds true are selectable |
limit | false | Integer |
The maximum number of rows that can be returned |
allow_aggregations | false | Boolean |
Toggle allowing aggregate queries |
drop_select_permission¶
The drop_select_permission
is used to drop an existing select permission for a role on a table.
An example:
POST /v1/query HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin
{
"type" : "drop_select_permission",
"args" : {
"table" : "article",
"role" : "user"
}
}
create_update_permission¶
An update permission is used to restrict the columns and rows that can be updated. Its structure is quite similar to the select permission.
An example:
POST /v1/query HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin
{
"type" : "create_update_permission",
"args" : {
"table" : "article",
"role" : "user",
"permission" : {
"columns" : ["title", "content", "category"],
"filter" : {
"author_id" : "X-HASURA-USER-ID"
},
"check" : {
"content" : {
"_ne": ""
}
},
"set":{
"updated_at" : "NOW()"
}
}
}
}
This reads as follows - for the user
role:
- Allow updating only those rows where the
filter
passes i.e. the value of theauthor_id
column of a row matches the value of the session variableX-HASURA-USER-ID
. - If the above
filter
passes for a given row, allow updating only thetitle
,content
andcategory
columns (as specified in thecolumns
key). - After the update happens, verify that the
check
condition holds for the updated row i.e. that the value in thecontent
column is not empty. - When this update happens, the value of the column
updated_at
will be automaticallyset
to the current timestamp.
Note
It is important to deny updates to columns that will determine the row
ownership. In the above example, the author_id
column determines the
ownership of a row in the article
table. Columns such as this should
never be allowed to be updated.
Args syntax¶
Key | Required | Schema | Description |
---|---|---|---|
table | true | TableName | Name of the table |
role | true | RoleName | Role |
permission | true | UpdatePermission | The permission definition |
comment | false | text | Comment |
UpdatePermission¶
Key | Required | Schema | Description |
---|---|---|---|
columns | true | PGColumn array (or) '*' |
Only these columns are selectable (or all when '*' is specified) |
filter | true | BoolExp | Only the rows where this precondition holds true are updatable |
check | false | BoolExp | Postcondition which must be satisfied by rows which have been updated |
set | false | ColumnPresetsExp | Preset values for columns that can be sourced from session variables or static values. |
drop_update_permission¶
The drop_update_permission
API is used to drop an existing update permission for a role on a table.
An example:
POST /v1/query HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin
{
"type" : "drop_update_permission",
"args" : {
"table" : "article",
"role" : "user"
}
}
create_delete_permission¶
A delete permission is used to restrict the rows that can be deleted.
An example:
POST /v1/query HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin
{
"type" : "create_delete_permission",
"args" : {
"table" : "article",
"role" : "user",
"permission" : {
"filter" : {
"author_id" : "X-HASURA-USER-ID"
}
}
}
}
This reads as follows:
“delete
for the user
role on the article
table is allowed on rows where
author_id
is the same as the request header X-HASURA-USER-ID
value.”
Args syntax¶
Key | Required | Schema | Description |
---|---|---|---|
table | true | TableName | Name of the table |
role | true | RoleName | Role |
permission | true | DeletePermission | The permission definition |
comment | false | text | Comment |
drop_delete_permission¶
The drop_delete_permission
API is used to drop an existing delete permission for a role on a table.
An example:
POST /v1/query HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin
{
"type" : "drop_delete_permission",
"args" : {
"table" : "article",
"role" : "user"
}
}
set_permission_comment¶
set_permission_comment
is used to set/update the comment on a permission.
Setting the comment to null
removes it.
An example:
POST /v1/query HTTP/1.1
Content-Type: application/json
Authorization: Bearer <auth-token> # optional if cookie is set
X-Hasura-Role: admin
{
"type": "set_permission_comment",
"args": {
"table": "article",
"role": "user",
"type" : "update",
"comment" : "can only modify his/her own rows"
}
}