Photon events

Photon distributes events and exposes delivery metadata within an authorized workspace. It helps applications inspect what was accepted, where it was sent, and which deliveries need attention.

Events and delivery

An event has a contract and belongs to a tenant and environment. Subscriptions determine eligible destinations. Acceptance records an event for processing; delivery records what happened when Photon attempted to send it to a destination. Inspect delivery metadata to understand outcomes before requesting recovery actions.

Permissions and availability

The installed Photon runtime must have its product session integration, workspace binding and resource policies configured. Discovery, metadata reads, payload reads, publishing and recovery operations each require their corresponding permission. This guide starts with scope discovery. Confirm publishing and retry or replay access separately for your application.

Quickstart — discover your scopes

Complete browser sign-in on the configured Photon product origin. Use the current opaque tab context and CSRF value with the session cookie. Set photonApiBase to the installed Photon API prefix, such as the approved same-origin proxy prefix, and environment to a configured environment name.

const url = new URL(photonApiBase + '/v1/events/scopes', location.origin)
url.searchParams.append('environment', environment)
const response = await fetch(url, {
  headers: {
    'X-Primia-Context': context,
    'X-Primia-CSRF': csrf,
  },
})
if (!response.ok) throw new Error('Scope discovery failed')
const { scopes, nextCursor } = await response.json()

Use the BFF cookie for this browser flow. Adding an Authorization header selects the workload-token path, which rejects unscoped discovery. Each returned scope has its own discovery decision within the admitted tenant. Use the returned tenantId and environment when selecting the scope for subsequent authorized operations.

Errors and next steps

If access is denied, check the session, current workspace, CSRF value and discovery permission. A workforce source hold or expired observation can also deny access until eligibility is refreshed. Once discovery succeeds, request the metadata operations enabled for the selected scope. Payload inspection and retry or replay require additional grants.