Skip to main content
An installation combines approved permissions with project scope. They answer different questions: what can the App do, and which projects can it do it in?

​
Permission and project rules

Customers select projects during installation and can adjust them under Integrations → Apps → Project access. The current model does not provide a per-project permission matrix such as read-only on A and read/write on B. Project access is enforced by Photon for API calls and App event delivery. Do not replace these checks with a browser checkbox or a filter in your own server. Changes to delivery targets propagate through reconciliation; do not describe saving a selection as erasing already-delivered data or canceling requests already in flight.

​
When the developer changes requested permissions

The App definition can change. Existing installations retain their approved configuration until an authorized customer reviews and approves the update. Increasing the developer’s requested permissions does not silently grant them to existing installations. Adding projects to an existing installation uses its approved permissions, including while an App update is pending. Reviewing an App update and changing project scope are separate customer actions.

​
Project discovery

With organization:read_projects, your installation can call the organization project-list API. Paginate through its results. That list is organization discovery, not a statement that the installation can access every returned project. A later project API request still requires both the relevant permission and project scope. Use the installation’s access token to read its own approved configuration:
The response includes the installation, App, organization and service-identity IDs, approved App version, effective permissions, approved event subscription, project scope, and installation version. It contains no secrets or pending App permission changes. This operation requires installation credentials and no additional organization permission. An App assertion, webhook signing secret, or ordinary service identity cannot substitute for those credentials. projectScope has one of these forms:
In all mode, the empty array means all current and future projects, not no access. In selected mode, only the listed projects are included; an empty list grants no project access. To resolve project names, use the project-list API with organization:read_projects and apply the returned scope. Subsequent API calls remain subject to current authorization. The Dashboard reads and edits project scope using the signed-in administrator’s management APIs. Your App uses its installation credentials for the self-view above. Keep customer Dashboard sessions and developer-organization credentials out of your App’s runtime integration.

​
Channel filtering is not channel authorization

Current installation scope selects projects, not individual channels inside each project. An App may filter received events by platform (for example, email versus iMessage), including different filters for different projects if its own implementation supports that model. Such filtering happens after the data reaches the App. It therefore cannot satisfy a requirement that the App must never receive or access a particular channel’s data. That requires Photon-enforced channel authorization, which is separate future work. Event-type subscriptions also do not provide a per-project channel permission boundary.

​
Lifecycle actions

The current App integration does not send an uninstall webhook to your backend. When Photon rejects access because an installation has been revoked, stop using its credentials and mark the connection disconnected in your product. Do not rely on an uninstall notification to trigger your cleanup workflow. Maintain a clear disconnected/recovery state in your product. A previously stored token, event, or list of projects is not proof of current authorization.