How it works
- Serve a manifest and your agent’s public keys over HTTPS.
- Send Photon a signed installation request that names the manifest URL.
- Photon fetches the manifest and shows the customer administrator what the App requests.
- The administrator chooses an organization and projects, and approves.
- Exchange the callback code for the installation’s credentials.
- Photon delivers signed events to the event URL in the manifest, and your agent calls the API with the installation’s access token.
Compared with a registered App
An App installed by manifest uses the same endpoints as an App registered in Photon Dashboard, the customer administrator sees the same approval and management pages, and events are signed the same way. Where a registered App sends itspho_app_… ID, send the manifest URL instead: in appId when you create and redeem an installation request, and in the iss and sub claims of the App assertion.
Manifest
The manifest is a Client ID Metadata Document with one additional object,photon. The following example is a complete manifest:
The
photon object has these fields:
Whether you serve your public keys at
jwks_uri or inline them in jwks, the key set holds 1 to 16 keys. Each key is ES256 (P-256) or RS256 (2048 bits or more) and has a unique kid.
Photon ignores other fields, such as logo_uri.
Requirements
Serve the manifest from a URL that:- Uses
httpsand is reachable from the public internet without authentication. - Has a path other than
/. - Has no fragment, no username or password, and no
.or..path segments.
- Every URL uses
httpsand resolves to a public address, not a private or reserved one. - There is no
client_secret, and notoken_endpoint_auth_methodthat uses a shared secret. The installation’s client secret is issued separately, as described in Limitations.
- Return status
200with a JSON body. Photon does not follow redirects. - Be at most 64 KB and respond within 5 seconds.
Discovery
Photon publishes its endpoints and supported options athttps://api.photon.codes/.well-known/openapp.json. The document requires no authentication. Placeholders on this page, such as {token_endpoint}, refer to its fields:
App assertion
Some requests identify the App rather than an installation: creating and redeeming an installation request, syncing the manifest, and rotating a client secret. For these, sign a JWT with one of the App’s private keys and send it asclientAssertion. The claims are the same as for a registered App, with the manifest URL as the App ID.
An assertion identifies the App. It does not grant access to customer data, which comes from the installation’s credentials.
To rotate a key, publish the new key and start signing with it. Photon reads your key set again when it sees a
kid it does not recognize.
Install
Installation follows the same four steps as for a registered App. Install an App covers session handling andstate in detail.
1. Create an installation request
Create an installation request that names the manifest URL asappId:
redirectUri must exactly match one of the manifest’s redirect_uris.
The response contains requestId, appId, appVersion, state, and redirectUri. Redirect the browser to the installation_approval_endpoint from the discovery document:
2. Let the customer administrator approve
The approval page shows the manifest’s domain, the App’s name, the permissions and events it requests, and the domain of the event URL. The administrator chooses the organization and the projects, and approves. If the organization already has an installation of this App, the page says that approving will issue new credentials for it. An installation request is valid for the manifest it was created with. If the manifest changes before the administrator approves, create a new request.3. Redeem the code
Photon redirects the browser toredirectUri with code and state. Exchange the code using a new assertion:
client_id identifies the App. The clientId in this response belongs to one installation, and you use it to get tokens. Install an App lists the other values of status.
Redeem the code within 5 minutes of approval.
If the organization already has an installation of this App, a successful redemption replaces its client secret. Until then, the current secret keeps working:
Do not retry redemption in a loop. When a response does not contain a secret you can use, start a new installation request for the same organization. The installation gets new credentials after the administrator approves.
4. Get an access token
Send the installation’s credentials to thetoken_endpoint from the discovery document:
access_token as a bearer token when you call the API, as in Send a reply through the API.
Verify events
Photon signs each delivery with the App’s webhook signing secret, following Standard Webhooks. Verification works the same way as for a registered App: use thewhsec_… value from the redemption response with a maintained verifier, and pass it the raw request body before any JSON parsing.
app_installation_id in the body is one of your installations, as described in Route by installation.
Update the manifest
The manifest is the only place to edit the App’s configuration. New installation requests always read the deployed manifest. To apply a change to existing installations, deploy the changed manifest and ask Photon to read it again:
Until the administrator approves, each installation keeps the configuration it was approved with. The administrator reviews the update on the installation’s page in Photon Dashboard, as described in Permissions and lifecycle.
Neither a sync nor an approved update changes the installation’s credentials, and approving an update is not the same as installing the App again. If Photon cannot read the manifest or rejects it, the sync changes nothing.
Check an installation’s status
To check an installation’s status, call this endpoint with the installation’s access token:pendingUpdate describes changes that are waiting for the customer administrator, and it is null when there are none:
Rotate the client secret
To replace an installation’s client secret, send a request that carries both the installation’s access token and an App assertion. The assertion must come from the App the installation belongs to. Otherwise, Photon rejects the request and the current secret keeps working.
Rotation does not revoke access tokens that were already issued. They keep working until they expire. To stop an installation’s access immediately, the customer administrator needs to suspend it.
Production and preview deployments
Each manifest URL is a separate App with its own installations. A production deployment and a preview deployment that serve different manifest URLs are two Apps, and a customer administrator approves each one. Serve each production agent’s manifest from a stable URL under your long-term control, such as the agent’s own domain. If the URL changes with every deployment, each deployment is a new App, and customers need to install it again. Photon does not have separate test and production environments. The administrator chooses the projects each App can access, so a customer can keep a project for testing and approve a preview deployment for that project only.Common situations
Limitations
- Token endpoint authentication. The token endpoint accepts
client_secret_postand does not supportprivate_key_jwt. Use the manifest URL and an App assertion during installation and sync, and use the installation’s client secret at runtime. - Webhook signing secret rotation. The webhook signing secret cannot be rotated yet.
- Resource selection. Access is granted per project. A manifest cannot limit the App to one channel inside a project.
- Readiness. The installation status reports approval and pending updates. It does not report whether a project’s channels are set up or whether your event URL is reachable.