import Thumbnail from '@site/src/components/Thumbnail'; import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem';

Backend Only Mutations

Introduction

Backend only permissions in Hasura allow certain mutations to be hidden from the public-facing API while still accessible via a trusted backend. This is useful for operations that should bypass standard client-side validation or business logic, ensuring that only authorized back-end services can perform these operations.

Setting "backend only" is available for insert, update and delete mutations.

<Tabs groupId="user-preference" className="api-tabs"> <TabItem value="console" label="Console"> Set a mutation permission for a role as backend only in the Hasura Console under **Data -> [table] -> Permissions -> [role] -> insert / update / delete -> Backend only** <Thumbnail src="/img/auth/allow-backends-only_console_2.10.1.png" alt="Allow backends only in Hasura Console" width="600px" /> </TabItem> <TabItem value="cli" label="CLI"> Set a mutation permission for a role as backend only in the `metadata -> databases -> [database-name] -> tables -> [table-name].yaml` file, e.g., `public_users.yaml`:

yaml

table:
  name: users
  schema: public
insert_permissions:
  - role: user
    permission:
      check: {}
      columns:
        - id
      backend_only: true
delete_permissions:
  - role: user
    permission:
      backend_only: true
      filter: {}

</TabItem> <TabItem value="api" label="API">

Set a mutate permission for a role as backend only with the Metadata API using the insert, update, or delete permissions.

http

POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin
{
  "type": "pg_create_insert_permission",
  "args": {
    "table": {
      "name": "users",
      "schema": "public"
    },
    "role": "user",
    "permission": {
      "check": {},
      "columns": [
        "id"
      ],
      "set": {},
      "backend_only": true
    },
    "source": "default"
  }
}

</TabItem> </Tabs>

:::info Supported from

Backend only permissions for update and delete mutations are supported in Hasura GraphQL Engine versions v2.8.0 and above.

:::

How it Works

Scenarios

Backend only permissions create two operation modes within Hasura:

Frontend Scenario: All mutation operations are visible when no backend-only permissions are set.
Backend Scenario: Specific mutations set with backend-only permissions become visible only when the x-hasura-use-backend-only-permissions header is set to true.

Schema Generation

Hasura maintains two GraphQL schemas per role per table:

Schema Type	Description	Example
Frontend Schema	Visible mutations without backend-only permissions.	Given a role "public" and a table "user", mutations like `insert_user` and `delete_user` are visible by default.
Backend Schema	Mutations visible only when backend-only permissions are enabled.	For the same role and table, the `update_user` mutation is only visible when the `x-hasura-use-backend-only-permissions` header is set to `true`.

All operations are visible by default.

Access Requirements

For a mutation to be accessible under backend only permissions, the following conditions must be met:

x-hasura-admin-secret is present if authorization is configured.
x-hasura-use-backend-only-permissions must be set to true.
x-hasura-role is used to identify the role.

This table outlines the visibility of mutations based on the Backend Only permission along with the presence of necessary headers:

Backend Only	`x-hasura-admin-secret`	`x-hasura-use-backend-only-permissions`	Result
FALSE	ANY	ANY	Always Visible
TRUE	FALSE	ANY	Always Hidden
FALSE	TRUE	ANY	Always Visible
TRUE	TRUE (OR NOT-SET)	FALSE	Hidden
TRUE	TRUE (OR NOT-SET)	TRUE	Shown