tauri-syntax-permissions

tauri-syntax-permissions

This system is NEW IN TAURI 2 — it replaces the v1 allowlist entirely. Claude frequently generates v1-style allowlist config which does not exist in v2.

Quick Reference

Permission Naming Convention

Format	Example	Description
<plugin>:default	fs:default	Default safe permissions for a plugin
<plugin>:allow-<command>	fs:allow-read-file	Allow a specific command
<plugin>:deny-<command>	fs:deny-write-file	Deny a specific command
<plugin>:<custom-set>	fs:read-files	Custom permission set
core:<module>:default	core:window:default	Core module defaults
core:<module>:allow-<cmd>	core:window:allow-set-title	Allow specific core command
allow-<command>	allow-greet	Custom app command (no plugin prefix)

File Locations

File	Location	Format	Purpose
Capability files	src-tauri/capabilities/*.json	JSON or TOML	Assign permissions to windows
App permissions	src-tauri/permissions/*.toml	TOML only	Define custom command permissions
Generated schemas	src-tauri/gen/schemas/	JSON	IDE autocompletion

Capability File Properties

Property	Type	Required	Description
$schema	string	No	Path to generated schema for IDE support
identifier	string	Yes	Unique capability name
description	string	No	Purpose description
windows	string[]	Yes	Window labels ("*" for all)
permissions	string[]	Yes	Permission identifiers
platforms	string[]	No	"linux", "macOS", "windows", "iOS", "android"
remote	object	No	Remote URL access config

---

Critical Warnings

NEVER use Tauri v1 allowlist syntax in tauri.conf.json — the allowlist was completely removed in v2. Use capability files instead.

NEVER assume plugins have permissions by default — installing a plugin crate and npm package does NOT grant any permissions. You MUST add permissions to a capability file or commands will fail with "command not allowed".

NEVER use "windows": ["*"] with broad permissions in production — this grants every window the same access. Use specific window labels.

NEVER write application permission definitions in JSON format — app-level permissions in src-tauri/permissions/ MUST be TOML. Only capability files support JSON.

ALWAYS add core:default or the specific core:*:default permissions your app needs — core features (window management, events, paths, menus) require explicit permissions in v2.

ALWAYS run cargo build after modifying permission/capability files — permissions are validated and compiled at build time.

---

Essential Patterns

Pattern 1: Minimal Capability File

{
  "$schema": "../gen/schemas/desktop-schema.json",
  "identifier": "default",
  "description": "Default capabilities for the main window",
  "windows": ["main"],
  "permissions": [
    "core:default",
    "core:window:default",
    "core:app:default"
  ]
}

Save as src-tauri/capabilities/default.json. Files in the capabilities/ directory are automatically enabled.

Pattern 2: Plugin Permissions

{
  "$schema": "../gen/schemas/desktop-schema.json",
  "identifier": "default",
  "description": "Main window with plugin access",
  "windows": ["main"],
  "permissions": [
    "core:default",
    "core:window:default",
    "core:app:default",
    "core:event:default",
    "core:path:default",
    "fs:default",
    "fs:allow-read-file",
    "dialog:default",
    "dialog:allow-open",
    "shell:default",
    "http:default",
    "notification:default",
    "clipboard-manager:allow-read",
    "clipboard-manager:allow-write"
  ]
}

Pattern 3: Custom Command Permissions

Step 1 — Define the Rust command:

#[tauri::command]
fn save_document(title: String, content: String) -> Result<(), String> {
    // ... save logic
    Ok(())
}

// Register in builder:
tauri::Builder::default()
    .invoke_handler(tauri::generate_handler![save_document])

Step 2 — Create permission file (src-tauri/permissions/my-commands.toml):

[[permission]]
identifier = "allow-save-document"
description = "Allows invoking the save_document command"
commands.allow = ["save_document"]

[[permission]]
identifier = "deny-save-document"
description = "Denies the save_document command"
commands.deny = ["save_document"]

Step 3 — Add to capability file (src-tauri/capabilities/default.json):

{
  "$schema": "../gen/schemas/desktop-schema.json",
  "identifier": "default",
  "windows": ["main"],
  "permissions": [
    "core:default",
    "allow-save-document"
  ]
}

Note: Custom app command permissions do NOT use a plugin prefix.

Pattern 4: Scope Configuration

# src-tauri/permissions/file-access.toml

[[permission]]
identifier = "scope-documents"
description = "Access to user documents directory"

[[scope.allow]]
path = "$DOCUMENT/*"

[[scope.deny]]
path = "$DOCUMENT/.secret/*"

{
  "permissions": [
    "fs:default",
    "fs:allow-read-file",
    "scope-documents"
  ]
}

Pattern 5: Permission Sets

Bundle multiple permissions under a single identifier:

# src-tauri/permissions/document-editor.toml

[[set]]
identifier = "document-editor-full"
description = "All permissions for the document editor feature"
permissions = [
    "fs:default",
    "fs:allow-read-file",
    "fs:allow-write-file",
    "dialog:allow-open",
    "dialog:allow-save",
    "allow-save-document",
    "allow-load-document"
]

Pattern 6: Platform-Specific Capabilities

{
  "$schema": "../gen/schemas/desktop-schema.json",
  "identifier": "desktop-only",
  "windows": ["main"],
  "platforms": ["linux", "macOS", "windows"],
  "permissions": [
    "global-shortcut:allow-register",
    "global-shortcut:allow-unregister"
  ]
}

{
  "$schema": "../gen/schemas/mobile-schema.json",
  "identifier": "mobile-only",
  "windows": ["main"],
  "platforms": ["iOS", "android"],
  "permissions": [
    "nfc:allow-scan",
    "biometric:allow-authenticate",
    "barcode-scanner:allow-scan"
  ]
}

Pattern 7: Remote API Access

{
  "$schema": "../gen/schemas/remote-schema.json",
  "identifier": "remote-capability",
  "windows": ["main"],
  "remote": {
    "urls": ["https://*.example.com"]
  },
  "platforms": ["iOS", "android"],
  "permissions": [
    "nfc:allow-scan",
    "barcode-scanner:allow-scan"
  ]
}

---

Common Plugin Permission Identifiers

Plugin	Default	Common Allow	Common Deny
fs	fs:default	fs:allow-read-file, fs:allow-write-file, fs:allow-mkdir	fs:deny-write-file
dialog	dialog:default	dialog:allow-open, dialog:allow-save, dialog:allow-message	—
shell	shell:default	shell:allow-open, shell:allow-execute	—
http	http:default	http:allow-fetch	—
notification	notification:default	notification:allow-notify	—
clipboard-manager	—	clipboard-manager:allow-read, clipboard-manager:allow-write	—
process	—	process:allow-restart, process:allow-exit	—
updater	updater:default	updater:allow-check, updater:allow-download-and-install	—
os	os:default	os:allow-platform	—
global-shortcut	—	global-shortcut:allow-register	—

Core Module Permissions

Module	Default	Example Allow
core:app	core:app:default	core:app:allow-version
core:window	core:window:default	core:window:allow-set-title, core:window:allow-close
core:event	core:event:default	core:event:allow-listen, core:event:allow-emit
core:path	core:path:default	core:path:allow-resolve
core:menu	core:menu:default	—
core:tray	core:tray:default	—
core:resources	core:resources:default	—

---

Window Merging Behavior

When a window appears in multiple capability files, all permissions from all capabilities are merged additively. There is no override or conflict resolution — permissions accumulate.

---

Schema Generation

Tauri generates JSON schemas in src-tauri/gen/schemas/:

• desktop-schema.json
• mobile-schema.json
• remote-schema.json

Reference via $schema for IDE autocompletion. These schemas are regenerated on build.

---

Inline Capabilities in tauri.conf.json

Capabilities can also be defined inline (less common):

{
  "app": {
    "security": {
      "capabilities": [
        {
          "identifier": "inline-capability",
          "windows": ["*"],
          "permissions": ["fs:default"]
        },
        "my-external-capability"
      ]
    }
  }
}

---

Reference Links

• references/methods.md — Complete permission and capability format reference
• references/examples.md — Complete capability file examples for common scenarios
• references/anti-patterns.md — What NOT to do, with WHY explanations

Official Sources

• https://v2.tauri.app/security/permissions/
• https://v2.tauri.app/security/capabilities/
• https://v2.tauri.app/develop/plugins/