Permissions

All 55 permissions a plugin can request, the methods each one unlocks, and how the install dialog rates them.

On this page

Risk levels
Project: read
Project: write
Editor
File system
Backups
Import
Export
User interface
Application settings
Plugin storage
Plugin settings
Format conversion
Debugging
Network
Media
Implicit grants
Declared, not yet callable

A plugin asks for permissions in the scopes array of its manifest. They get approved once, at install, and checked again on every single call afterwards. Nothing is cached into a token, and nothing is taken on the plugin's word.

Risk levels

Assigned by the host in SCOPE_RISK_MAP, not by this documentation. This is the same classification the install dialog uses.

Low

Reads data, or shows a message

27 permissions

Medium

Renders UI, or registers a handler

10 permissions

High

Modifies project data, writes files, or reaches the network

18 permissions

Project: read

project.read Low

project.getMetadata()

Granted for free by: export.project

project.read.analytics Low

project.getWordCountLog() project.getWritingGoals() project.getWritingMinutesLog()

Granted for free by: export.project

project.read.cardboards Low

project.getCardboards()

Granted for free by: export.project

project.read.characters Low

project.getCharacterById() project.getCharacters()

Granted for free by: export.project

project.read.collections Low

project.getCollections()

Granted for free by: export.project

project.read.docContent Low

project.getDocContent()

Granted for free by: export.project

project.read.docs Low

project.getDocs()

Granted for free by: export.project

project.read.fileContent Low

project.getFileContent()

Granted for free by: export.file , export.book , export.project

project.read.files Low

project.getFiles() project.getFolders()

Granted for free by: export.book , export.project

project.read.flowmaps Low

project.getFlowMaps()

Granted for free by: export.project

project.read.images Low

project.getImageData() project.getImages()

Granted for free by: export.project

project.read.notes Low

project.getNotes()

Granted for free by: export.project

project.read.plotgrid Low

project.getPlotGrids()

Granted for free by: export.project

project.read.scenes Low

project.getScenes()

Granted for free by: export.project

project.read.snapshots Low

project.getFileSnapshots()

Granted for free by: export.project

project.read.tags Low

project.getTags()

Granted for free by: export.project

project.read.templates Low

project.getCustomWorldbuildingTemplates()

Granted for free by: export.project

project.read.timelines Low

project.getTimelines()

Granted for free by: export.project

project.read.worldbuilding Low

project.getWorldbuilding() project.getWorldbuildingByType()

Granted for free by: export.project

Project: write

project.write.cardboards High

Declared in the enum, but no API method requires it yet.

project.write.characters High

project.addCharacter() project.updateCharacter()

project.write.docs High

project.addDoc() project.updateDocMeta()

project.write.fileContent High

project.updateDocContent() project.updateFileContent()

Granted for free by: import.file , import.project

project.write.files High

project.addFile() project.updateFileMeta()

Granted for free by: import.project

project.write.images High

project.addImage()

project.write.notes High

project.addNote()

project.write.plotgrid High

Declared in the enum, but no API method requires it yet.

project.write.tags High

project.updateTags()

project.write.worldbuilding High

project.addWorldbuildingElement() project.removeWorldbuildingElement() project.updateWorldbuildingElement()

Editor

editor.read Low

editor.getActiveDocument() editor.getOpenDocuments() editor.getSelection() editor.getWordCount()

Granted for free by: editor.write

editor.write High

editor.insertAt() editor.replaceRange() editor.replaceSelection()

Also grants: editor.read

File system

fs.platform Low

fs.getPlatform()

fs.read Medium

fs.readProjectFile()

fs.write High

fs.deleteProjectFile() fs.saveProject() fs.writeProjectFile()

Backups

backup.create Medium

backup.create()

backup.list Medium

backup.getById() backup.list()

backup.restore High

backup.restore()

Import

import.file Medium

import.registerImporter()

Also grants: project.write.fileContent

import.project High

import.registerProjectImporter()

Also grants: project.write.fileContent , project.write.files

Export

export.book High

export.registerBookExporter()

Also grants: project.read.fileContent , project.read.files

export.file Medium

export.exportFile() export.registerExporter()

Also grants: project.read.fileContent

User interface

ui.contextMenu Medium

Declared in the enum, but no API method requires it yet.

ui.dialog Medium

ui.closeDialog() ui.openDialog()

ui.notification Low

ui.showNotification()

ui.window Medium

ui.hideSidebar() ui.isFullscreen() ui.showSidebar() ui.toggleFullscreen() ui.toggleSidebar()

Application settings

app.settings.read Low

app.getSettings() app.getSettingsField()

Granted for free by: app.settings.write

app.settings.write High

app.updateSettings()

Also grants: app.settings.read

Plugin storage

storage Low

storage.get() storage.getAll() storage.remove() storage.set()

Plugin settings

settings Low

settings.get() settings.getField()

Format conversion

convert.format Low

convert.fromHtml() convert.fromMarkdown() convert.fromText() convert.toHtml() convert.toMarkdown() convert.toText()

Debugging

debug.console Low

debug.clear() debug.getLogs()

Network

net.fetch High

net.fetch()

Media

media.control Medium

media.getNowPlaying() media.getState() media.next() media.pause() media.play() media.previous() media.resume() media.setVolume() media.stop()

Implicit grants

Some permissions hand you others, because the operation is impossible without them. Declare the one on the left and you get the ones on the right. Declaring both only makes your install dialog longer.

Declaring	also grants
export.file	project.read.fileContent
import.file	project.write.fileContent
app.settings.write	app.settings.read
editor.write	editor.read
export.book	project.read.fileContent project.read.files
export.project	project.read project.read.characters project.read.worldbuilding project.read.files project.read.fileContent project.read.docs project.read.docContent project.read.notes project.read.plotgrid project.read.cardboards project.read.images project.read.collections project.read.tags project.read.analytics project.read.timelines project.read.flowmaps project.read.templates project.read.snapshots project.read.scenes
import.project	project.write.fileContent project.write.files

Declared, not yet callable

3 permissions exist in the enum but no API method requires them yet. They are valid in a manifest, and the installer accepts them, but they unlock nothing today. Listed here rather than hidden, because they are the ones most likely to gain methods next.

ui.contextMenu project.write.cardboards project.write.plotgrid