Skip to main content
Registration creates the App definition. It does not install the App into a customer organization.

​
Create the definition

In your developer organization, open Developer → Apps → New app. Use an account authorized to manage Apps in that organization. The callback and webhook are different endpoints. The callback is a browser redirect with a short-lived installation code. The webhook receives HTTP POST deliveries when subscribed events occur, even when no user has your website open. Use HTTPS URLs reachable by Photon. For local development, a tunnel can forward HTTPS traffic to your server. Keep the registered callback exactly aligned with the redirectUri you send when starting installation, including its path and trailing slash.

​
Choose permissions and events together

Request only capabilities your product uses. Organization permissions apply at the organization level. Project permissions apply to the projects approved for an installation. For the local walkthrough, request:
  • organization:read: resolve the installation’s organization through /v1/organizations/current.
  • messages:read: receive message events.
  • Subscribe to message.received and configure your event webhook URL.
If your App sends replies, it also needs the current API’s project:write permission. If it lists organization projects, it needs organization:read_projects. Do not request billing or other unrelated access just to make installation work. An event subscription is not a permission grant. Photon must also authorize delivery using the installation’s approved permissions and project scope. Changing a subscription does not bypass customer consent.

​
Save both App-level keys

After creation:
  1. Record the App ID (pho_app_…) and signing key ID.
  2. Save the downloaded ES256 private key (.pem) in your backend’s secret store. Keep its contents out of source control, browser code, recordings, and logs.
  3. In Webhook signing secret, reveal and save the whsec_… value for your backend’s webhook verifier.
The webhook secret is shared across installations of this App. Route each verified event to its installation; the signature alone does not identify which of your customers should receive it. The webhook-key metadata operation reports whether a key exists and has been revealed, plus a fingerprint. It does not return the secret. Reveal is the separate secret-delivery operation. Treat reveal as a setup step, not a way for customers to retrieve installation credentials. Idempotent replay of the original reveal operation may return its original response; do not treat it as a key-rotation mechanism.
The current Dashboard has no self-service rotation or recovery action for App signing keys or webhook signing secrets. Save both securely during setup. If you lose either value, contact Photon support for recovery assistance before resuming the affected operations. A replacement generated only on your backend will not match the key registered with Photon.
The current Dashboard generates a new Key ID when importing your own public JWK or PEM, including when the JWK already contains a kid. Use the Key ID displayed by Photon as the assertion JWT’s kid, together with the corresponding private key on your backend. This describes the Dashboard import flow; do not assume the imported JWK’s original kid is the registered value.

​
Offer installation from your product

Place a Connect to Photon button in your product that starts your backend’s installation flow. A marketplace listing is not required. Registration, customer consent, and webhook delivery work with a direct installation entry point. Next: Implement installation.