Permissions

Introduction

Access control rules are essential for securing your data and ensuring that only authorized users can access it. In Hasura, these are referred to as permissions. You can use permissions to control access to certain rows or columns in your database, or to restrict access to certain operations or fields in your GraphQL API.

The following types of permissions can be defined:

Type	Description
TypePermissions	Define which fields are allowed to be accessed by a role on an output type.
ModelPermissions	Define which objects or rows within a model are allowed to be accessed by a role.
CommandPermissions	Define whether the command is executable by a role.

LSP-assisted authoring

Permissions are written in your various HML files. If you're using a compatible editor (such as VS Code with the Hasura extension), LSP-assisted authoring will help you write permissions more efficiently. LSP will provide you with auto-completion, syntax highlighting, and error checking as you write your permissions.

Metadata structure

TypePermissions

Definition of permissions for an OpenDD type.

Key	Value	Required	Description
kind	TypePermissions	true
version	v1	true
definition	TypePermissionsV1	true	Definition of permissions for an OpenDD type.

TypePermissionsV1

Definition of permissions for an OpenDD type.

Key	Value	Required	Description
typeName	CustomTypeName	true	The name of the type for which permissions are being defined. Must be an object type.
permissions	[TypePermission]	true	A list of type permissions, one for each role.

Example:

typeName: article
permissions:
  - role: admin
    output:
      allowedFields:
        - article_id
        - author_id
        - title
  - role: user
    output:
      allowedFields:
        - article_id
        - author_id

TypePermission

Defines permissions for a particular role for a type.

Key	Value	Required	Description
role	Role	true	The role for which permissions are being defined.
output	TypeOutputPermission / null	false	Permissions for this role when this type is used in an output context. If null, this type is inaccessible for this role in an output context.

Example:

role: user
output:
  allowedFields:
    - article_id
    - author_id

TypeOutputPermission

Permissions for a type for a particular role when used in an output context.

Key	Value	Required	Description
allowedFields	[FieldName]	true	Fields of the type that are accessible for a role

FieldName

The name of a field in a user-defined object type.

Value: string

Role

The role for which permissions are being defined.

Value: string

CustomTypeName

The name of a user-defined type.

Value: string

ModelPermissions

Definition of permissions for an OpenDD model.

Key	Value	Required	Description
kind	ModelPermissions	true
version	v1	true
definition	ModelPermissionsV1	true	Definition of permissions for an OpenDD model.

ModelPermissionsV1

Definition of permissions for an OpenDD model.

Key	Value	Required	Description
modelName	ModelName	true	The name of the model for which permissions are being defined.
permissions	[ModelPermission]	true	A list of model permissions, one for each role.

Example:

modelName: Articles
permissions:
  - role: admin
    select:
      filter: null
  - role: user
    select:
      filter:
        fieldComparison:
          field: author_id
          operator: _eq
          value:
            sessionVariable: x-hasura-user-id

ModelPermission

Defines the permissions for an OpenDD model.

Key	Value	Required	Description
role	Role	true	The role for which permissions are being defined.
select	SelectPermission / null	false	The permissions for selecting from this model for this role. If this is null, the role is not allowed to query the model.

Example:

role: user
select:
  filter:
    fieldComparison:
      field: author_id
      operator: _eq
      value:
        sessionVariable: x-hasura-user-id
  argument_presets:
    - field: likes_dogs
      value:
        literal: true

SelectPermission

Defines the permissions for selecting a model for a role.

Key	Value	Required	Description
filter	null / ModelPredicate	true	Filter expression when selecting rows for this model. Null filter implies all rows are selectable.
argumentPresets	[ArgumentPreset]	false	Preset values for arguments for this role

ArgumentPreset

Preset value for an argument

Key	Value	Required	Description
argument	ArgumentName	true	Argument name for preset
value	ValueExpression	true	Value for preset

ArgumentName

Argument name for preset

Value: string

ModelPredicate

A predicate that can be used to restrict the objects returned when querying a model.

Must have exactly one of the following fields:

Key	Value	Required	Description
fieldComparison	FieldComparisonPredicate	false	Field comparison predicate filters objects based on a field value.
fieldIsNull	FieldIsNullPredicate	false	Predicate to check if the given field is null.
relationship	RelationshipPredicate	false	Relationship predicate filters objects of a source model based on a predicate on the related model.
and	[ModelPredicate]	false
or	[ModelPredicate]	false
not	ModelPredicate	false

Example:

fieldComparison:
  field: author_id
  operator: _eq
  value:
    sessionVariable: x-hasura-user-id

RelationshipPredicate

Relationship predicate filters objects of a source model based on a predicate on the related model.

Key	Value	Required	Description
name	RelationshipName	true	The name of the relationship of the object type of the model to follow.
predicate	ModelPredicate / null	false	The predicate to apply on the related objects. If this is null, then the predicate evaluates to true as long as there is at least one related object present.

RelationshipName

The name of the GraphQL relationship field.

Value: string

FieldIsNullPredicate

Predicate to check if the given field is null.

Key	Value	Required	Description
field	FieldName	true	The name of the field that should be checked for a null value.

FieldComparisonPredicate

Field comparison predicate filters objects based on a field value.

Key	Value	Required	Description
field	FieldName	true	The field name of the object type of the model to compare.
operator	string	true	The name of the operator to use for comparison.
value	ValueExpression	true	The value expression to compare against.

ValueExpression

An expression which evaluates to a value that can be used in permissions.

Must have exactly one of the following fields:

Key	Value	Required	Description
literal		false
sessionVariable	string	false

FieldName

The name of a field in a user-defined object type.

Value: string

Role

The role for which permissions are being defined.

Value: string

ModelName

The name of data model.

Value: string

CommandPermissions

Definition of permissions for an OpenDD command.

Key	Value	Required	Description
kind	CommandPermissions	true
version	v1	true
definition	CommandPermissionsV1	true	Definition of permissions for an OpenDD command.

CommandPermissionsV1

Definition of permissions for an OpenDD command.

Key	Value	Required	Description
commandName	CommandName	true	The name of the command for which permissions are being defined.
permissions	[CommandPermission]	true	A list of command permissions, one for each role.

Example:

commandName: get_article_by_id
permissions:
  - role: admin
    allowExecution: true
  - role: user
    allowExecution: true

CommandPermission

Defines the permissions for a role for a command.

Key	Value	Required	Description
role	Role	true	The role for which permissions are being defined.
allowExecution	boolean	true	Whether the command is executable by the role.
argumentPresets	[ArgumentPreset]	false	Preset values for arguments for this role

Example:

role: user
allowExecution: true
argumentPresets:
  - argument: user_id
    value:
      session_variable: x-hasura-user_id

ArgumentPreset

Preset value for an argument

Key	Value	Required	Description
argument	ArgumentName	true	Argument name for preset
value	ValueExpression	true	Value for preset

ValueExpression

An expression which evaluates to a value that can be used in permissions.

Must have exactly one of the following fields:

Key	Value	Required	Description
literal		false
sessionVariable	string	false	Used to represent the name of a session variable, like "x-hasura-role".

ArgumentName

Argument name for preset

Value: string

Role

The role for which permissions are being defined.

Value: string

CommandName

The name of a command.

Value: string