Skip to main content
A Photon App lets your service receive events and call APIs on behalf of an organization that installs it. Register the App once; each customer installation has its own approved permissions, project access, and API credentials.
This guide describes the Beta App installation flow. Confirm that Apps and project access are enabled in your target environment before testing. Use the API, Dashboard, and token endpoint from the same environment. Use installation credentials to read the installation’s approved permissions and project scope through GET /v1/installations/current, as explained in Project discovery.

​
Who does what?

In Photon Dashboard, Developer → Apps manages Apps you build. Integrations → Apps manages Apps installed in the current organization. You may use the same organization for both roles during development; they are still separate operations. Your backend can serve many customers. It does not need a separate deployment or .env file for each installation. Store each customer’s installation record in your backend’s persistent storage and associate it with the correct account in your own product.

​
Two integration directions

The webhook receiver is an HTTPS endpoint you operate. It can be part of your existing backend; a separate relay service is not required. In the Convex prototype, the demo web server also hosts this backend and forwards verified events to Convex. That is one implementation of the generic flow.

​
Three credentials with different jobs

A PEM file is a key file, not an installation access token. The webhook secret verifies incoming deliveries; it does not authenticate outgoing API calls. End users installing your App do not download keys or edit environment variables.

​
Build the integration

  1. Register your App and declare its capabilities.
  2. Implement installation and save per-installation credentials.
  3. Receive events and call APIs.
  4. Handle permissions and lifecycle changes.
  5. Run the local server walkthrough.