> ## Documentation Index
> Fetch the complete documentation index at: https://docs.photon.codes/docs/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Use Stable documentation by default. Honor an explicit Beta request or a URL under /docs/beta/. If the requested version conflicts with the installed CLI package or API origin, clarify the target before writing integration code.
> Pages under /docs/beta/ document Beta; other product pages document Stable. Keep the CLI package, commands, API origin, and credentials within the selected version. State the documentation version in your answer.
> For MCP search, always pass version: Stable or version: Beta. Unfiltered search mixes both versions. For filesystem reads, keep Beta queries under /beta/ and exclude /beta/ from Stable queries; discover paths before reading them.
> The public docs base is https://photon.codes/docs. Convert MCP page paths to public URLs under that base, preserving /beta/ when present. Read https://photon.codes/docs/skill.md for version selection and https://photon.codes/docs/llms.txt for the version indexes.

# Permissions and lifecycle

> Understand approved permissions, project scope, App updates, and installation lifecycle changes.

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

| Setting | Effect |
| - | - |
| Organization permissions | Authorize organization-level operations independently of project selection. |
| Project permissions | The same approved set applies to every project in the installation's scope. |
| All projects | Includes existing projects and projects created in the organization later. |
| Only selected projects | Includes only explicitly selected projects; future projects are not added automatically. |
| Add a project after installation | Gives that project the installation's **currently approved** permissions. It does not approve pending App permission changes. |
| Remove a project | Removes that project's access for the installation, covering API access and event delivery. It cannot erase data already received by the App. |

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:

```http theme={null}
GET /v1/installations/current
Authorization: Bearer INSTALLATION_ACCESS_TOKEN
```

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:

```json theme={null}
{ "mode": "all", "projectIds": [] }
```

```json theme={null}
{ "mode": "selected", "projectIds": ["pho_prj_EXAMPLE"] }
```

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

| Action | Meaning for the integration |
| - | - |
| Suspend an installation | Keeps it installed but stops its active access until resumed. Stop customer operations when authorization fails. |
| Resume an installation | Restores access subject to its approved permissions and current scope. |
| Uninstall | Revokes the installation's access. Previously copied data in your product is governed by your retention/deletion policy. |
| Disable an App definition | Prevents new installations; existing installations continue to work. |
| Retire an App definition | Stops its credentials and initiates removal across installations. This is not a temporary pause. |

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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.