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.

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**

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`:

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: {}

API

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

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"
  }
}

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