meta.json and approved by the user.
A permission not in this list is a manifest error, so a typo is caught at load rather than at the call.
files, server and echo are new in 2.1; declaring one requires "sdkVersion": "^2.1.0".What needs no permission
Pages, the sidebar, injections, editors, creators, item types, settings tabs, and reading and writing your own settings; themes, language, icons; notifications; dialogs other than the file and item pickers; commands, keybindings, CLI commands, menus, toolbars, the status bar, panels, routes, widgets and apps; events and interceptors; AI tools; scripting targets; your own storage and private data folder; Minecraft data, text helpers and YAML; background scripts; services; undo; team presence. Some of these touch exports, imports or the server, but only see what they are handed:- Exporters and importers run only when the user picks them, and see only what that export or import hands them.
- A module’s own export and validation functions see only items that use that module.
- Logic-editor catalog entries, Coder formats and linters are data and per-file checks.
- Server status, reload commands, sync hooks, sync-script directives and server types do not send anything themselves.
- SFTP hooks receive the project id, the push message and the file list, never file contents.
- Echo context and AI tools add to what Echo and connected assistants see and can do. A tool that is not
readOnlyasks the user before it runs. Asking Echo yourself is what needsecho. - Scripting targets only see the script bundle the export hands them.
How approval works
1
Needs approval
An expansion that declares permissions loads as Needs approval and does not run.
2
Review permissions
The user presses Review permissions on the Expansions page and sees the plain-language lines above.
3
Approved
On approval the expansion starts. The grant is remembered.
Being refused
A call without its permission throwsSdkPermissionError (async calls reject with it) and logs:
fetch and WebSocket without network reject with a message naming your expansion. Nothing is half-done; the call simply does not happen.
Asking for less
Declare only what you use. Every permission is a line the user reads before saying yes, and an expansion that asks for nothing starts immediately. If a feature needs a permission, consider putting the feature behind a button rather than making the whole expansion wait on approval. A few patterns that avoid a permission altogether:- Keep your own data in
sdk.storagerather than in the project. - To change what a plugin config contains, prefer a module export, which needs nothing, over an export transform, which sees every item and needs
project:read.
What the environment gives you anyway
Inside your code you have standard JavaScript (Promise, Map, JSON, Intl, URL, TextEncoder, crypto, Blob, AbortController, structuredClone, Image, Audio, …), console, and timers that are cleaned up when your expansion unloads.
You do not have window, document, require, process, localStorage or the app’s internals. fetch and WebSocket exist only with network; sockets are closed when your expansion unloads.