> ## 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. # Register an App > Configure your App's callback, event receiver, permissions, and signing keys. 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. | Field | What to enter | Example | | - | - | - | | App name | The name customers see during installation | `Helpdesk Sync` | | Description | What your App does with their data | `Sync incoming messages to our support inbox.` | | Website | Your product's website; optional | `https://helpdesk.example.com` | | HTTPS callback | Your backend endpoint for completing installation after consent | `https://helpdesk.example.com/photon/callback` | | Requested permissions | The organization and project capabilities your App needs | `organization:read`, `messages:read` | | Event webhook URL | Your backend endpoint that receives signed events | `https://helpdesk.example.com/photon/webhooks` | | Subscribed events | The event types your backend handles | `message.received` | 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](https://docs.photon.codes/docs/beta/apps/quickstart.md), 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. > [!WARNING] > > 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](https://docs.photon.codes/docs/beta/apps/install.md). This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.