Permissions
What a plugin can declare, which permissions apply on install, and which stay off until the user grants them.
A plugin lists what it needs in its manifest:
"permissions": ["storage", "network", "field.write"],"hosts": ["api.open-meteo.com"]Most plugins declare [] and need nothing. Every declared permission is shown
to the user before they install, on the addon page and in the file-import
confirmation.
Permissions come in three kinds:
| Kind | What happens |
|---|---|
| Listed | Applies as soon as the plugin is installed. Shown in the list before install. |
| Risky | Shown before install in a separate, warned block. Off until the user turns it on on the plugin’s page, after reading a warning, and only while WM Keyboard Tools Plugins Allow risky permissions is on. |
| Not available | Things no permission grants, listed below. |
Plugins written for API 4 can declare only storage, reminders and
selection. Everything else needs "apiVersion": 5.
Listed permissions
Section titled “Listed permissions”storage
Section titled “storage”Gives you storage, and secrets for API keys.
- Local to the device and to your plugin. No other plugin can read it.
- Deleted when the user uninstalls you, and clearable by them any time from WM Keyboard Tools Plugins Manage plugins your plugin. An update leaves it alone.
- API 4: 128 keys, 64 characters per key, 8 KB per value, 64 KB in total. API 5: 512 keys, 64 KB per value, 1 MB in total.
- Values in
secretsare encrypted like the keyboard’s own API keys and never appear in the storage inspector or a backup.
reminders
Section titled “reminders”Ask the app to show a line of text in a notification at a time you set.
from wm import remindersreminders.set("item:7", time.time() + 3600, "Buy milk")- The app shows it, not your script. No plugin code runs in the background, and none runs when it fires.
- The title is always your plugin’s name, so a reminder cannot pretend to come from the system or another app.
- 64 pending, 200 characters of text, up to ten years ahead.
selection
Section titled “selection”Adds buttons to the bar over selected text, listed under actions in the
manifest. Your script sees the selection only when the user tapped one of your
buttons on it, never on a password field. See
Selection actions.
field.write (API 5)
Section titled “field.write (API 5)”Type, replace the selection, delete, move the cursor and press the field’s
action key, through field. The user sees every
change happen. Refused in password fields and incognito.
clipboard.write (API 5)
Section titled “clipboard.write (API 5)”Copy text with clipboard.set.
sensors (API 5)
Section titled “sensors (API 5)”Motion, light, pressure and step readings while your panel is open.
scan (API 5)
Section titled “scan (API 5)”Open the keyboard’s own QR and text scanners. You get the result, never the camera.
device (API 5)
Section titled “device (API 5)”Vibrate, turn on the flashlight, read text aloud, and read the battery level.
share (API 5)
Section titled “share (API 5)”Hand text to another app or open an https link. The keyboard always shows what is being shared, and where, before it goes.
notifications (API 5)
Section titled “notifications (API 5)”Show a notification, titled with your plugin’s name.
Risky permissions
Section titled “Risky permissions”Each of these is off after install. The user turns it on, one plugin at a time,
on the plugin’s page in
WM Keyboard Tools Plugins Manage plugins your plugin, after a
warning that says what it allows. A call before that raises PermissionError,
and the panel shows the permission with an Allow button that leads to the
same page.
| Permission | Gives you | Warning the user reads |
|---|---|---|
network | http: https requests to the hosts in hosts | Data you give the plugin can go to those websites, which see your IP address. |
ai | ai: the AI model the user set up | Text goes to that model, online or on the phone. |
field.read | field.selection(), field.text_before(), field.text_after(), field.info() | The plugin can read what you are writing, each time you tap something in its panel. |
clipboard.read | clipboard.get() | The plugin can read what you copied, each time you tap something in its panel. |
location | location.get() | The plugin can find out where your phone is while its panel is open. |
files | files.pick(), files.save() | The plugin can read every file you pick for it. |
Rules that hold whatever was granted:
- Reads need the user’s hand.
field.*reads andclipboard.getwork only while your plugin handles something the user did in its panel: a tap, a change, a submit, a key, a header button, a keyword chip. A timer, a network answer oron_opencannot call them, so a plugin cannot poll the field. - Never protected text. Password fields, incognito, and clips marked private are refused.
- Network rules. https only, to a host your manifest lists (exactly, or
under a
*.entry) or one the user typed into ahostsetting. No IP addresses orlocalhost. Every redirect is checked again. Replies up to 1 MB, 15 seconds at most, 60 requests a minute. Nothing is sent while Data saver is on, and every request appears in the keyboard’s Network activity under your plugin’s name. - Only while open. Timers, sensors and streams stop when your panel or floating box closes. In the floating box a plugin keeps running over the app with the keyboard closed, until the user closes the box; its text boxes never type there, because tapping one moves the plugin into the keyboard.
When a plugin can read something of the user’s and send data away (for
example field.read with network), the install screen says so in plain
words: “This plugin can read text or files you give it and send them to
api.example.com.”
An update that adds a risky permission, or a host, leaves it off, and the plugin’s page says what is new.
Required with network, unless a host setting lets the user type their own
server:
"hosts": ["api.open-meteo.com", "*.openfoodfacts.org"]At most 16. Host names only: no scheme, port or path.
What no permission allows
Section titled “What no permission allows”| What the user types | No key event API. |
| Text outside your own boxes, without the user acting | Field reads only happen inside a user’s action in your panel. |
| Password fields and incognito text | Refused in every build. |
| Background work | Nothing of yours runs while none of your panels is open. A reminder is text the app shows. |
| Downloaded code | No eval, exec or compile, and import reaches your own files and the bundled library only. |
| Android itself | Only the named host calls. No Intents, no file paths, no reflection. |
| Your own look | Every widget is drawn by the keyboard in its theme; colours are roles like danger, never values. |
Getting text without reading it
Section titled “Getting text without reading it”You often do not need field.read at all.
In: draw an input. The user types into it, or taps Paste beside it. They can see exactly what they gave you.
Out: draw an output. The keyboard puts an Insert button under it.
Both at once: a selection action. The user selects text and taps your button, and what you return replaces it.
Security covers how all of this is enforced.
