Permissions
Extensions that need to trigger Lumio actions (send chat messages, control OBS scenes, emit events) must declare the required permissions in lumio.config.json.
Declaring permissions
{
"permissions": ["chat:send", "obs:set_scene"]
}
Declared permissions are shown to users during installation. Users must explicitly grant consent before the extension can use them.
Available permissions
| Permission | Action | Notes |
|---|---|---|
"chat:send" | Send a message to the platform chat | Sent by the bot that serves the account's chat (on Twitch, the Lumio bot) |
"chat:read" | Receive chat messages (for commands, keywords, patterns) | Required for bot modules that process chat. In a widget or layer, useLumioEvent() receives chat:message, twitch:chat, youtube:chat, kick:chat, twitch:ban and twitch:unban only with this permission |
"events:read" | Receive platform events (follows, subs, raids, Spotify, …) | In a widget or layer, useLumioEvent() receives every non-chat event type only with this permission (useLumioEvent) |
"chat:delete" | Delete a chat message by ID | Runs as the account's own bot, which must be a channel moderator (Twitch, YouTube). Enhanced review. |
"chat:ban" | Ban a user | Runs as the account's own bot, which must be a channel moderator (Twitch, YouTube). Enhanced review. |
"chat:unban" | Lift a ban | Runs as the account's own bot, which must be a channel moderator (Twitch). Enhanced review. |
"chat:timeout" | Time out a user | Runs as the account's own bot, which must be a channel moderator (Twitch, YouTube). Enhanced review. |
"obs:set_scene" | Switch the active OBS scene | Requires OBS WebSocket to be connected |
"obs:set_source_visible" | Show or hide an OBS source | Requires OBS WebSocket to be connected |
"obs:start_stream" | Start the OBS stream | Requires OBS WebSocket to be connected |
"obs:stop_stream" | Stop the OBS stream | Requires OBS WebSocket to be connected |
"obs:start_recording" | Start the OBS recording | Requires OBS WebSocket to be connected |
"obs:stop_recording" | Stop the OBS recording | Requires OBS WebSocket to be connected |
"spotify:play" | Resume playback or play a track | Requires a connected Spotify account |
"spotify:pause" | Pause playback | Requires a connected Spotify account |
"spotify:skip" | Skip to the next track | Requires a connected Spotify account |
"spotify:seek" | Seek within the current track | Requires a connected Spotify account |
"spotify:volume" | Set the player volume | Requires a connected Spotify account |
"spotify:shuffle" | Turn shuffle on or off | Requires a connected Spotify account |
"spotify:repeat" | Set the repeat mode | Requires a connected Spotify account |
"spotify:queue_add" | Add a track to the queue | Requires a connected Spotify account |
"sounds:play" | Play or stop a sound in a browser source | Sound must exist in the account's sound library |
"events:emit" | Emit a custom Lumio event | Triggers automations and other extensions listening for this event |
"overlay:update_layer" | Toggle the visibility of another overlay layer | Must be on the same overlay |
Using permissions
Request the permission with useLumioAction() in your extension:
import { useLumioAction, Button } from "@zaflun/lumio-sdk";
function SendChatButton() {
const { execute: sendChat, isLoading } = useLumioAction("chat:send");
return (
<Button
label="Send to chat"
onClick={() => sendChat({ platform: "twitch", message: "Game is starting!" })}
disabled={isLoading}
/>
);
}
The permission you declare is exactly the string you pass to useLumioAction() - each action maps to its own granular permission, and there are no coarse capability groupings (e.g. there is no obs:control that unlocks every OBS action; declare obs:set_scene to switch scenes, obs:start_stream to start the stream, and so on).
If the permission is not declared in lumio.config.json, the action call is rejected at runtime with a permission error. The action also needs the plan feature of the service it drives (feature:music for Spotify, feature:obs_remote for OBS, feature:multichat for chat); see useLumioAction. Chat actions run as the account's bot; see useLumioAction → Chat for the platform matrix and error codes.
Admin review
Permissions are reviewed during the extension approval process. Reviewers check:
- Does the declared permission match the extension's stated purpose?
- Does the code actually use the declared permission?
- Are any undeclared permissions used in the code?
Extensions that declare permissions they do not use, or use permissions they did not declare, are rejected.
Enhanced review
Permissions marked with Enhanced review (chat:ban, chat:delete) trigger additional manual code review during the store approval process. Reviewers verify that moderation logic is sound and cannot be exploited for mass-banning or mass-deletion. Extensions requesting these permissions may take longer to approve.
User consent
When a user installs an extension that declares permissions:
- The installation wizard shows a list of all requested permissions
- The user must click Grant permissions to proceed
- A user can revoke permissions later in the extension settings
- If permissions are revoked,
useLumioAction()calls return an error
Future permissions
Additional permissions will be added as new Lumio actions are introduced. Check this page for updates. Custom permissions (for inter-extension communication via events:emit) use the standard events:emit permission with a custom event type.