> ## 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.

# Publish an App manifest

> Publish a manifest on your agent's own domain and install the App by its URL, without registering it in Photon Dashboard.

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](https://docs.photon.codes/docs/beta/apps/register.md).

## 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:

```mermaid theme={null}
flowchart LR
  subgraph D["Your deployment"]
    M["Manifest<br/>https://agent.example/photon"]
    K["Public keys"]
    E["Event URL"]
  end
  subgraph P["Photon"]
    A["App<br/>identified by the manifest URL"]
    O["openapp.json"]
  end

  P -- "fetches" --> M
  P -- "fetches" --> K
  P -- "signed events" --> E
  D -. "reads endpoints" .-> O
```

## 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.

| | Registered in Photon Dashboard | Installed by manifest |
| - | - | - |
| App identity | `pho_app_…` | The manifest URL |
| Configuration | Edited in Photon Dashboard | Edited in the manifest, then synced |
| Public keys | Uploaded at registration | Read from the manifest |
| Webhook signing secret | Revealed in Photon Dashboard | Returned when you redeem an installation ([Verify events](#verify-events)) |

## Manifest

The manifest is a [Client ID Metadata Document](https://datatracker.ietf.org/doc/draft-ietf-oauth-client-id-metadata-document/) with one additional object, `photon`. The following example is a complete manifest:

```json theme={null}
{
  "client_id": "https://agent.example/photon",
  "client_name": "Customer Support Agent",
  "client_uri": "https://agent.example",
  "redirect_uris": ["https://agent.example/api/photon/callback"],
  "jwks_uri": "https://agent.example/.well-known/jwks.json",
  "photon": {
    "schema_version": "1",
    "description": "Receive customer messages and reply.",
    "permissions": ["messages:read", "project:write"],
    "events": {
      "api_version": "2026-07-01",
      "types": ["message.received"],
      "url": "https://agent.example/api/photon/events"
    }
  }
}
```

| Field | Type | Required | Description |
| - | - | - | - |
| `client_id` | string | Yes | The manifest URL. It must match the URL the manifest is served from exactly. |
| `client_name` | string | Yes | The name shown to the customer administrator. |
| `client_uri` | string | No | The App's website. |
| `redirect_uris` | string\[] | Yes | 1 to 32 HTTPS callback URLs. |
| `jwks_uri` | string | Either this or `jwks` | The URL of the App's public keys. |
| `jwks` | object | Either this or `jwks_uri` | The App's public keys, inline. |
| `photon` | object | Yes | Photon-specific configuration. |

The `photon` object has these fields:

| Field | Type | Required | Description |
| - | - | - | - |
| `schema_version` | string | Yes | Must be `"1"`. |
| `description` | string | No | A brief description shown to the customer administrator. |
| `permissions` | string\[] | Yes | The permissions the App requests. [Register an App](https://docs.photon.codes/docs/beta/apps/register.md#choose-permissions-and-events-together) explains how to choose them. |
| `events` | object | No | The event subscription. Omit it if your agent receives no events. |
| `events.api_version` | string | Yes, with `events` | The event API version, currently `2026-07-01`. |
| `events.types` | string\[] | Yes, with `events` | The event types to deliver. |
| `events.url` | string | Yes, with `events` | The event URL: the HTTPS URL that receives events. |

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](#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:

```json theme={null}
{
  "name": "Photon",
  "manifest_schema_versions_supported": ["1"],
  "client_assertion_signing_alg_values_supported": ["ES256", "RS256"],
  "token_endpoint_auth_methods_supported": ["client_secret_post"],
  "installation_request_endpoint": "https://api.photon.codes/v1/installation-requests",
  "installation_approval_endpoint": "https://app.beta.photon.codes/organization/install",
  "installation_redeem_endpoint": "https://api.photon.codes/v1/installation-requests/redeem",
  "app_sync_endpoint": "https://api.photon.codes/v1/apps/sync",
  "installation_status_endpoint": "https://api.photon.codes/v1/installations/current",
  "client_secret_rotation_endpoint": "https://api.photon.codes/v1/installations/current/client-secret/rotate",
  "token_endpoint": "https://auth.photon.codes/oauth2/token"
}
```

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.

| Claim/header | Value |
| - | - |
| `alg`, `kid` | The algorithm and key ID of a key in the manifest. |
| `iss`, `sub` | The manifest URL. |
| `aud` | The absolute URL of the endpoint you are calling. |
| `iat`, `exp` | The current time, and an expiry at most 5 minutes later. |
| `jti` | A unique random ID. Photon accepts each assertion once. |

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](https://docs.photon.codes/docs/beta/apps/install.md) covers session handling and `state` in detail.

```mermaid theme={null}
sequenceDiagram
  participant App as Your agent
  participant P as Photon
  actor Admin as Customer administrator

  App->>P: POST /v1/installation-requests (assertion)
  P->>App: Fetches manifest and keys
  P-->>App: requestId
  App->>Admin: Redirect to the Photon approval page
  Admin->>P: Choose organization and projects, approve
  P-->>App: Redirect to redirectUri with code and state
  App->>P: POST /v1/installation-requests/redeem (new assertion)
  P-->>App: installationId, clientId, clientSecret, webhookSigningSecret
```

### 1. Create an installation request

Create an installation request that names the manifest URL as `appId`:

```http theme={null}
POST /v1/installation-requests
Content-Type: application/json

{
  "appId": "https://agent.example/photon",
  "clientAssertion": "SIGNED_JWT",
  "state": "RANDOM_SESSION_BOUND_STATE",
  "redirectUri": "https://agent.example/api/photon/callback"
}
```

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:

```text theme={null}
{installation_approval_endpoint}?requestId={requestId}
```

### 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:

```http theme={null}
POST /v1/installation-requests/redeem
Content-Type: application/json

{
  "appId": "https://agent.example/photon",
  "code": "CALLBACK_CODE",
  "clientAssertion": "NEW_SIGNED_JWT"
}
```

The response carries the installation's credentials and the App's webhook signing secret:

```json theme={null}
{
  "status": "created",
  "installationId": "pho_ain_EXAMPLE",
  "clientId": "client_EXAMPLE",
  "clientSecret": "SECRET_RETURNED_ONLY_ONCE",
  "webhookSigningSecret": "whsec_EXAMPLE"
}
```

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](https://docs.photon.codes/docs/beta/apps/install.md#a-successful-http-response-may-not-contain-credentials) 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:

| What happens | Result |
| - | - |
| The code is redeemed | The new secret replaces the current one. |
| The code is not redeemed in time, for example because the browser was closed before the callback | The current secret keeps working. Start a new installation request to try again. |
| The redemption succeeds, but you do not receive the response | The previous secret has stopped working, and redeeming again returns `delivery_consumed` without the secret. Start a new installation request, and use the secret from the next redemption. |

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:

```http theme={null}
POST {token_endpoint}
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id=CLIENT_ID&client_secret=CLIENT_SECRET
```

Use the response's `access_token` as a bearer token when you call the API, as in [Send a reply through the API](https://docs.photon.codes/docs/beta/apps/webhooks.md#send-a-reply-through-the-api).

## Verify events

Photon signs each delivery with the App's webhook signing secret, following [Standard Webhooks](https://www.standardwebhooks.com/). 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.

```ts theme={null}
import { Webhook } from "standardwebhooks";

const verifier = new Webhook(process.env.PHOTON_WEBHOOK_SIGNING_SECRET);
const event = verifier.verify(rawBody, headers);
```

The verifier checks the signature and that the timestamp is recent. [Verify before parsing or processing](https://docs.photon.codes/docs/beta/apps/webhooks.md#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](https://docs.photon.codes/docs/beta/apps/webhooks.md#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:

```http theme={null}
POST /v1/apps/sync
Content-Type: application/json

{
  "appId": "https://agent.example/photon",
  "clientAssertion": "SIGNED_JWT"
}
```

The response reports the configuration version Photon now holds. The version changes only when the configuration changes:

```json theme={null}
{
  "appId": "https://agent.example/photon",
  "appVersion": "7"
}
```

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:

| Change | Takes effect for existing installations |
| - | - |
| Name, description, website, redirect URIs, public keys | When the sync succeeds |
| Permissions, event types, event API version, event URL | After the customer administrator approves |

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](https://docs.photon.codes/docs/beta/apps/permissions.md#when-the-developer-changes-requested-permissions).

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:

```http theme={null}
GET /v1/installations/current
Authorization: Bearer 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:

```json theme={null}
{
  "appId": "https://agent.example/photon",
  "installationId": "pho_ain_EXAMPLE",
  "organizationId": "pho_org_EXAMPLE",
  "approvedAppVersion": "6",
  "effectivePermissions": ["messages:read"],
  "approvedEventSubscription": {
    "apiVersion": "2026-07-01",
    "events": ["message.received"]
  },
  "projectScope": { "mode": "selected", "projectIds": ["pho_prj_EXAMPLE"] },
  "pendingUpdate": {
    "appVersion": "7",
    "permissionsAdded": ["project:write"],
    "permissionsRemoved": [],
    "eventsAdded": [],
    "eventsRemoved": [],
    "eventApiVersionChanged": false,
    "eventUrlChanged": false
  }
}
```

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.

```http theme={null}
POST /v1/installations/current/client-secret/rotate
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json

{
  "clientAssertion": "SIGNED_JWT",
  "mode": "normal"
}
```

Photon returns the new secret once:

```json theme={null}
{
  "clientId": "client_EXAMPLE",
  "clientSecret": "SECRET_RETURNED_ONLY_ONCE",
  "previousSecretValidUntil": "2026-12-01T10:00:00Z"
}
```

| `mode` | The previous secret |
| - | - |
| `normal` | Keeps working for 1 hour. |
| `emergency` | Stops working immediately. |

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

| Situation | What happens |
| - | - |
| Two organizations install the same manifest URL | Each organization gets its own installation. |
| An organization installs a manifest URL it already installed | Photon does not create a second installation. The installation keeps its ID and project scope. Its current secret keeps working until the new one is redeemed, as described in [Redeem the code](#3-redeem-the-code). |
| The manifest moves to a new URL | The new URL is a new App, and customers need to install it again. |
| The manifest is no longer served | Installation requests and syncs fail. Existing installations keep working. |
| You lose the client secret | Start a new installation request for the same organization. You receive new credentials after the administrator approves. |
| You lose the webhook signing secret | The next successful redemption returns it again. If no installation is pending, start a new installation request for an organization that already has the App; it replaces that installation's client secret. |
| The manifest is served from a local machine | Photon cannot read it. Use a tunnel with a public HTTPS URL, or register an App in Photon Dashboard. |

## 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.