Install an App

Your backend performs the protocol steps. The customer clicks Connect to Photon, reviews access in Photon Dashboard, and returns to your product.

1. Create an installation request

Require a signed-in session in your product before starting. Generate a cryptographically random, expiring state and store it server-side with that session and customer account. Do not trust a customer ID supplied in an unverified callback. Sign a new JWT with your registered App private key:

Claim/header	Value
`alg`, `kid`	The registered key’s algorithm (`ES256` for generated keys and the local example; `RS256` for an imported RSA key) and its registered key ID
`iss`, `sub`	Your App ID
`aud`	The exact absolute URL of the endpoint being called
`iat`, `exp`	Current time and a short expiry; use two minutes, never more than five
`jti`	A new unique random ID for each assertion

Use a maintained JWT library such as jose. Keep your server clock synchronized. Do not reuse assertions or sign the request using the webhook secret.

POST /v1/installation-requests
Content-Type: application/json

{
  "appId": "pho_app_REPLACE_ME",
  "clientAssertion": "SIGNED_JWT",
  "state": "RANDOM_SESSION_BOUND_STATE",
  "redirectUri": "https://helpdesk.example.com/photon/callback"
}

The response includes requestId, appId, state, and redirectUri. Check the echoed fields against the request, then redirect the browser to:

{PHOTON_DASHBOARD_ORIGIN}/organization/install?requestId={requestId}

See Create installation request.

2. Let the customer approve access

Photon Dashboard handles Photon login and verifies that the user can manage App installations in the selected organization. This is separate from the login session in your own product. The customer reviews the requested permissions and chooses All projects or Only selected projects. All selected projects share the same approved project permissions. All projects includes projects created later; selected projects does not automatically include future projects. Customers can subsequently manage the installation under Integrations → Apps. See Permissions and lifecycle.

3. Validate the callback and redeem the code

On the registered HTTPS callback:

Validate the browser session and compare state with the unexpired server-side value. Reject missing, mismatched, expired, or already-used state.
Consume the state once. Do not let two callback requests redeem concurrently.
Exchange code server-to-server with a new assertion, whose audience is the redemption endpoint.

POST /v1/installation-requests/redeem
Content-Type: application/json

{
  "appId": "pho_app_REPLACE_ME",
  "code": "CALLBACK_CODE",
  "clientAssertion": "NEW_SIGNED_JWT"
}

A first successful delivery returns:

{
  "status": "created",
  "installationId": "pho_ain_REPLACE_ME",
  "clientId": "client_REPLACE_ME",
  "clientSecret": "SECRET_RETURNED_ONLY_ONCE"
}

Persist the credentials securely before showing success. Associate the installation ID with your product’s customer account, and resolve/verify its Photon organization using the installation’s access token. Never send the client secret or access token to the browser.

A successful HTTP response may not contain credentials

Redemption status	Handling
`created`	Persist the returned credentials; complete setup.
`delivery_consumed`	The one-time delivery has already been consumed. Use your securely stored credentials if available. Do not assume a retry will reveal them again.
`recovery_required`	Stop setup and follow installation credential recovery with Photon.
`revocation_pending`	Do not activate the connection while revocation is pending.
`revoked`	Do not use the installation’s credentials.

If redemption times out, the operation may have succeeded even though you did not receive the secret. Do not loop until a new secret appears, replace another installation’s credentials, or mark the connection successful. Preserve a non-secret diagnostic reference and initiate recovery. A browser refresh of an old callback cannot safely repeat installation. See Redeem installation credential.

4. Obtain an installation access token

Send the installation credentials to the token endpoint configured for your Photon environment. This is the environment’s AuthKit OAuth token endpoint, not /v1/installation-requests/redeem and not the legacy Stable OAuth API. Obtain its exact URL from Photon when enabling App access; do not infer it from the Dashboard hostname or send credentials to a URL supplied by an end user.

POST {PHOTON_TOKEN_URL}
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id=CLIENT_ID&client_secret=CLIENT_SECRET

Use a form encoder to construct the body. Use the response’s access_token as a bearer token:

GET /v1/organizations/current
Authorization: Bearer ACCESS_TOKEN

This example requires organization:read. Cache tokens only until their expiry, keep them server-side, and handle authorization failures after an installation is paused, removed, or changes scope. Possessing an unexpired token does not override Photon authorization checks.

Store data per installation

Your persistent model should associate:

Your customer/account ID and the Photon installation ID.
The verified Photon organization ID.
Encrypted client credentials and connection status.
Event deduplication records and processing checkpoints.

App-level PEM and webhook signing secret are configured once per App/environment. Per-installation client credentials belong in storage, not a new .env file or a separate server for every customer.

Get started

Message Delivery

Apps

AI tools

Plans and billing

Security

Install an App

1. Create an installation request

2. Let the customer approve access

3. Validate the callback and redeem the code

A successful HTTP response may not contain credentials

4. Obtain an installation access token

Store data per installation

​1. Create an installation request

​2. Let the customer approve access

​3. Validate the callback and redeem the code

​A successful HTTP response may not contain credentials

​4. Obtain an installation access token

​Store data per installation

1. Create an installation request

2. Let the customer approve access

3. Validate the callback and redeem the code

A successful HTTP response may not contain credentials

4. Obtain an installation access token

Store data per installation