Permissions API - Eliza

The permissions API manages OS-level permissions (microphone, camera, screen recording, etc.) and the shell access toggle. Permission states are tracked in server memory and updated via Electrobun RPC in desktop deployments. Shell access controls whether the agent can execute terminal commands.

Endpoints

GET /api/permissions

Get all system permission states.

Response

Returns a flat map of permission ID to permission state:

json

{
  "accessibility": {
    "id": "accessibility",
    "status": "granted",
    "lastChecked": 1718000000000,
    "canRequest": false
  },
  "screen-recording": {
    "id": "screen-recording",
    "status": "granted",
    "lastChecked": 1718000000000,
    "canRequest": false
  },
  "microphone": {
    "id": "microphone",
    "status": "granted",
    "lastChecked": 1718000000000,
    "canRequest": false
  },
  "camera": {
    "id": "camera",
    "status": "denied",
    "lastChecked": 1718000000000,
    "canRequest": true
  },
  "shell": {
    "id": "shell",
    "status": "granted",
    "lastChecked": 1718000000000,
    "canRequest": false
  }
}

Each value is a permission state object with the following fields:

Field	Type	Description
`id`	string	Permission identifier
`status`	string	`"granted"`, `"denied"`, `"not-determined"`, `"restricted"`, or `"not-applicable"`
`lastChecked`	number	Unix ms timestamp of the last check
`canRequest`	boolean	Whether the app can request this permission via system prompt

GET /api/permissions/:id

Get the state of a single permission. Returns "not-applicable" status if the permission ID is not tracked.

Path Parameters

Parameter	Type	Required	Description
`id`	string	Yes	Permission identifier (e.g., `microphone`, `camera`, `screen-recording`)

Response

json

{
  "id": "microphone",
  "status": "granted",
  "lastChecked": 1718000000000,
  "canRequest": false
}

Field	Type	Description
`status`	string	`"granted"`, `"denied"`, `"not-determined"`, or `"not-applicable"`
`canRequest`	boolean	Whether the app can request this permission via system prompt

GET /api/permissions/shell

Get the shell access toggle status.

Response

json

{
  "enabled": true
}

PUT /api/permissions/shell

Toggle shell access on or off. When changed while the agent is running, schedules a runtime restart so plugin loading respects the new setting.

Request

json

{
  "enabled": false
}

Parameter	Type	Required	Description
`enabled`	boolean	Yes	`true` to allow shell command execution, `false` to block it

Response

Returns the updated shell permission state:

json

{
  "id": "shell",
  "status": "denied",
  "lastChecked": 1718000000000,
  "canRequest": true
}

PUT /api/permissions/state

Update permission states in bulk. Used by the Electrobun renderer after receiving updated permission states via RPC.

Request

json

{
  "permissions": {
    "microphone": {
      "id": "microphone",
      "status": "granted",
      "lastChecked": 1718000000000,
      "canRequest": false
    }
  }
}

Parameter	Type	Required	Description
`permissions`	object	Yes	Map of permission ID to permission state object

Response

json

{
  "updated": true,
  "permissions": { "microphone": { "id": "microphone", "status": "granted" } }
}

POST /api/permissions/refresh

Force refresh all permission states. In desktop deployments, this signals the renderer to re-check permissions via IPC.

Response

Returns the full permissions state map (same shape as GET /api/permissions).

POST /api/permissions/:id/request

Request a specific system permission. In desktop deployments, this triggers a native system permission prompt.

Path Parameters

Parameter	Type	Required	Description
`id`	string	Yes	Permission identifier

Response

json

{
  "message": "Permission request for microphone",
  "action": "ipc:permissions:request:microphone"
}

POST /api/permissions/:id/open-settings

Open system settings for a specific permission (e.g., macOS Privacy & Security settings).

Path Parameters

Parameter	Type	Required	Description
`id`	string	Yes	Permission identifier

Response

json

{
  "message": "Opening settings for microphone",
  "action": "ipc:permissions:openSettings:microphone"
}