Skip to main content
To connect an agent to Photon without registering an App in Photon Dashboard, publish a manifest on the agent’s domain. The manifest’s URL is the App’s identity in Photon, so you do not need a Photon account. After a customer administrator approves the App, your agent receives events and can call the API. To manage an App in Photon Dashboard instead, see Register an App.

How it works

  1. Serve a manifest and your agent’s public keys over HTTPS.
  2. Send Photon a signed installation request that names the manifest URL.
  3. Photon fetches the manifest and shows the customer administrator what the App requests.
  4. The administrator chooses an organization and projects, and approves.
  5. Exchange the callback code for the installation’s credentials.
  6. Photon delivers signed events to the event URL in the manifest, and your agent calls the API with the installation’s access token.
The diagram shows what Photon reads from your deployment and what it sends back:

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 its pho_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 https and 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.
Avoid a query string if you can. Photon compares URLs character by character, so two URLs that differ only in the query string are two Apps. Inside the manifest:
  • Every URL uses https and resolves to a public address, not a private or reserved one.
  • There is no client_secret, and no token_endpoint_auth_method that uses a shared secret. The installation’s client secret is issued separately, as described in Limitations.
Both the manifest and the key set must:
  • Return status 200 with a JSON body. Photon does not follow redirects.
  • Be at most 64 KB and respond within 5 seconds.
If the manifest breaks any of these rules, Photon rejects it and the error names the rule.

Discovery

Photon publishes its endpoints and supported options at https://api.photon.codes/.well-known/openapp.json. The document requires no authentication. Placeholders on this page, such as {token_endpoint}, refer to its fields:
Photon adds fields to this document over time. Ignore fields you do not recognize.

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 as clientAssertion. 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 and state in detail.

1. Create an installation request

Create an installation request that names the manifest URL as appId:
Photon fetches the manifest for every installation request, so the administrator always sees the version you have deployed. 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 to redirectUri with code and state. Exchange the code using a new assertion:
The response carries the installation’s credentials and the App’s webhook signing secret:
Photon returns the client secret once. The webhook signing secret belongs to the App, not the installation, so every successful redemption returns the same value. Store both before you show the customer that setup succeeded. The manifest’s 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 the token_endpoint from the discovery document:
Use the response’s 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 the whsec_… value from the redemption response with a maintained verifier, and pass it the raw request body before any JSON parsing.
The verifier checks the signature and that the timestamp is recent. Verify before parsing or processing covers the headers and common mistakes. The secret is shared by every installation of the App, so a valid signature does not say which customer the event is for. Check that 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:
The response reports the configuration version Photon now holds. The version changes only when the configuration changes:
Some changes take effect as soon as the sync succeeds. Changes to what the administrator approved wait for a new approval, even when they remove access: 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:
The response shows what the administrator approved. pendingUpdate describes changes that are waiting for the customer administrator, and it is null when there are none:
A suspended or uninstalled installation cannot get a token, so it cannot check its status.

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.
Photon returns the new secret once:
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_post and does not support private_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.