Permissions

File permissions control who can upload, download, replace, and delete files. They are managed per role in the dashboard.

Permissions follow a Zero Trust model — by default no role has access. Access must be explicitly granted.

Actions

Storage supports four permission actions:

• Upload — who can upload new files
• Download — who can view and download files
• Replace — who can overwrite existing files
• Delete — who can remove files

Configuring Permissions

In the dashboard, navigate to Storage and click Permissions at the bottom of the sidebar to see the permission grid. This grid shows every role and action at a glance — full access, partial access, or no access. Click any cell to configure that role’s permission for that action.

Permission options

Each action form has the following options:

• Without any checks — the role can perform the action on all files, no conditions.
• With custom check — use the rule editor to restrict which files the role can access (e.g. only files in a specific bucket, or only files the user uploaded).
• Permission presets — pre-built rules for common patterns.

Upload and Replace options

The Upload and Replace forms have an additional toggle:

• Uploader identity — automatically sets uploaded_by_user_id to X-Hasura-User-Id when files are created or replaced. This ensures every file is tagged with the uploader’s identity without relying on the client to send it.

Examples

Private Files — Users Access Only Their Own Files

The most common pattern. Users can upload, download, and delete only files they own, in a specific bucket.

Upload

In the permission grid, click the Upload cell for the user role.

1. Select With custom check and add a rule: bucket_id equals personal
2. Under Uploader identity, enable the Prefill uploaded_by_user_id with X-Hasura-User-Id toggle to automatically tag files with the uploader’s identity

Download

Click the Download cell for the user role.

1. Select With custom check and add two rules combined with AND:
   • uploaded_by_user_id equals X-Hasura-User-Id
   • bucket_id equals personal

Delete

Click the Delete cell for the user role.

1. Select With custom check and add the same rules as Download:
   • uploaded_by_user_id equals X-Hasura-User-Id
   • bucket_id equals personal

Public Read, Authenticated Write

Files in a public bucket can be downloaded by anyone (including the public role), but only authenticated users can upload.

Upload

Configure the Upload action for the user role:

1. Select With custom check and add a rule: bucket_id equals public
2. Under Uploader identity, enable the Prefill uploaded_by_user_id with X-Hasura-User-Id toggle

Download

For both the public and user roles, click the Download cell, select With custom check, and add a rule: bucket_id equals public.

This allows anyone to download files from the public bucket, whether authenticated or not, while keeping files in other buckets protected.

Multi-Tenant — Organization-Scoped Files

For multi-tenant applications where files belong to an organization. This uses a custom claim X-Hasura-Org-Id.

This example assumes you have a relationship from storage.files to your organizations table through a custom org_id column in your file metadata or through a linking table.

A simpler approach uses the file’s custom metadata JSONB column to store the organization ID, and a Hasura computed field or relationship to evaluate it.

Alternatively, you can create a dedicated organization_files table that references storage.files:

CREATE TABLE public.organization_files (
  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
  file_id uuid NOT NULL REFERENCES storage.files(id) ON DELETE CASCADE,
  org_id uuid NOT NULL REFERENCES public.organizations(id)
);

Then set permissions on this linking table using X-Hasura-Org-Id, and configure a relationship from storage.files to organization_files. For the storage permissions themselves:

Upload

Configure the Upload action for the user role:

1. Select With custom check and add a rule: bucket_id equals org-files
2. Under Uploader identity, enable the Prefill uploaded_by_user_id with X-Hasura-User-Id toggle

Download

Configure the Download action for the user role:

1. Select With custom check and add a rule using the relationship: organization_files.org_id equals X-Hasura-Org-Id

This ensures users can only download files belonging to their organization.

Role-Based Access

Different roles get different levels of access. For example, editor can upload and delete, while viewer can only download.

Editor Role

Upload: Select With custom check if you want to restrict to specific buckets, or Without any checks for all buckets. Under Uploader identity, enable the Prefill uploaded_by_user_id with X-Hasura-User-Id toggle.

Download: Select Without any checks — editors can view all files.

Delete: Select With custom check and add a rule: uploaded_by_user_id equals X-Hasura-User-Id. This lets editors delete only their own uploads.

Viewer Role

Download: Select Without any checks — viewers can view all files.

No Upload, Replace, or Delete permissions are configured for this role.

Tips

• Under Uploader identity, enable the Prefill uploaded_by_user_id with X-Hasura-User-Id toggle on Upload and Replace permissions to prevent users from impersonating others.
• Use custom checks on bucket_id to control which buckets a role can access.
• Use the public role for files that should be accessible without authentication.
• Combine bucket restrictions with ownership checks for fine-grained control.
• Test permissions by signing in as different users and verifying access is correctly scoped.

Caution

Deleting file metadata directly through GraphQL does not delete the actual file from S3. Always use the Storage API to delete files so both the metadata and the file content are removed.

Advanced

Storage permissions are built on Hasura’s permission system for the storage.files table. The dashboard configures these automatically, but understanding the underlying mapping can help with debugging or advanced setups.

How requests are authorized

When a user makes a request to the Storage API:

1. The Storage service extracts the JWT from the Authorization header
2. The JWT contains the user’s ID, role, and any custom claims
3. Storage forwards these as Hasura session variables (X-Hasura-User-Id, X-Hasura-Role, etc.)
4. Hasura evaluates the permission rules for the storage.files table
5. If the permission check passes, the operation proceeds

Permission variables

The following session variables are available in custom checks:

• X-Hasura-User-Id — the authenticated user’s ID
• X-Hasura-Role — the user’s role
• Custom claims like X-Hasura-Org-Id

Hasura permission mapping

Each dashboard action maps to a Hasura permission on the storage.files table:

Action	Hasura Permission	Required Columns
Upload	insert	id, bucket_id, name, size, mime_type
Download	select	All columns must be granted
Replace	update	bucket_id, etag, is_uploaded, metadata, mime_type, name, size
Delete	delete	—