Homey Apps SDK
📖 Apps SDK Reference🌍 Web API🛠 Developer Tools
  • Welcome to the Apps SDK documentation 👋
  • The Basics
    • Getting Started
      • Homey CLI
    • App
      • Manifest
      • Internationalization
      • Permissions
      • Persistent Storage
    • Drivers & Devices
      • Pairing
        • System Views
          • Devices List
          • Add Devices
          • OAuth2 Login
          • Credentials Login
          • Pincode
          • Loading
          • Done
        • Custom Views
      • Capabilities
      • Energy
      • Settings
      • Best practices
        • Lights
        • Window coverings
        • Battery status
    • Flow
      • Arguments
      • Tokens
    • Widgets
      • Settings
      • Styling
      • Debugging
  • Wireless
    • Wi-Fi
      • Discovery
    • Bluetooth LE
    • Z-Wave
    • Zigbee
    • 433 MHz
    • Infrared
    • Matter
  • Cloud
    • OAuth2
    • Webhooks
  • App Store
    • Publishing
    • Guidelines
    • Verified Developer
    • Updating
  • Advanced
    • Custom Views
      • App Settings
      • Custom Pairing Views
      • HTML & CSS Styling
    • Web API
    • Images
    • LED Ring
    • Homey Compose
  • Guides
    • Homey Cloud
    • Breaking Changes
    • Tools
      • Bluetooth LE
      • Zigbee
      • TypeScript
    • Using ESM in Homey Apps
  • Upgrade Guides
    • Homey v6.0.0
    • Upgrading to SDK v3
      • Zigbee Apps
    • Device Capabilities
Powered by GitBook
On this page
  • Available permissions
  • Which apps may use the API permission?
  • App-to-app communication

Was this helpful?

  1. The Basics
  2. App

Permissions

Homey Apps require permissions for certain functionality, learn which permissions exist and how to request them.

PreviousInternationalizationNextPersistent Storage

Last updated 1 year ago

Was this helpful?

Permissions are needed to allow Homey apps to use certain Apps SDK functionality. Most Homey Apps don't need any permissions. In case a permission is not requested by the App, the manager methods that require that permission will throw an error.

Permissions are added to your in an array named permissions.

/.homeycompose/app.json
{
  "id": "com.athom.example",
  // ...
  "permissions": [
    "homey:wireless:ble",
    "homey:app:com.athom.example"
  ]
}

An app should only request permissions it actually needs to function.

Apps will not automatically update on Homey when new permissions are added.

Available permissions

The following is a list of the permissions that an app may use.

Permission

Description

homey:manager:api

homey:manager:geolocation

homey:manager:ledring

homey:manager:speech-output

homey:wireless:433

homey:wireless:868

homey:wireless:ir

homey:wireless:ble

homey:wireless:nfc

Which apps may use the API permission?

The API permission ("homey:manager:api") allows an app to access the Homey Web API. This web api can be used to control all of Homey (devices, Flows, etc) even if they are not part of the App that requested the permission. This level of access can be used to add new advanced functionality to Homey. However because an app receives complete control over the Homey it is installed on this permission should only be requested when it is the main functionality of your app.

Apps that request the API permission will be reviewed more carefully when published to the App Store. If the permission is not required for your app to function your app submission will be rejected.

As a rule of thumb, only apps that add functionality to Homey that can be categorised in the Tools section, should use the API permission. For example apps that are allowed to use the API permission are: a DIY Home Alarm system, HomeyScript and Device Groups. Examples of apps that should not use the API permission are: those that connect to a physical device, e.g. a branded app for lightbulbs, thermostats etc.

App-to-app communication

Allows an app to use the methods to communicate with the Homey Web API.

With this permission an app can use to get the current location of the Homey.

Allows interacting with the Homeys LED Ring through .

This permission allows an app to make Homey speak using .

With this permission an app can call getSignal433 on to use the 433MHz antenna.

With this permission an app can call getSignal868 on to use the 868MHz antenna.

With this permission an app can call getSignalInfrared on to send IR signals.

Enables an app to use to discover Bluetooth devices and interact with them.

Allows an app to use to be notified of scanned NFC tags

Apps using the homey:manager:api permission are not allowed on Homey Cloud. Read more about this in the .

Apps can also talk to each other through their , however you need to define the correct permissions first. Permissions for app to app communication look like this homey:app:<appId>, where the appId is that of the app you want to communicate with. For example homey:app:com.athom.example or homey:app:com.yahoo.weather.

App-to-app communication is not supported on Homey Cloud. Read more about this in the .

For more information about app-to-app communication read the .

App Manifest
Homey Cloud guide
Web API
Homey Cloud guide
ManagerApi
ManagerGeolocation
ManagerLedring
ManagerSpeechOutput
ManagerRF
ManagerRF
ManagerRF
ManagerBLE
ManagerNFC
Web API guide