Build

Live sessions

Use live sessions to show transparency while Collate works or while a manual handoff is active. A live session is a read model, not a command surface.

Retrieve the live session

1GET /v1/prior-authorizations/auth_123/live-session
2Authorization: Bearer <API_KEY>

The response is always typed. When no channel session is available, state = not_live.

1{
2  "priorAuthorizationId": "auth_123",
3  "priorAuthorizationVersion": 8,
4  "state": "live",
5  "channel": "portal",
6  "owner": { "type": "automation", "manualHandoffId": null },
7  "access": {
8    "available": true,
9    "supportedModes": ["read_only"]
10  },
11  "handoff": {
12    "allowed": false,
13    "state": "unavailable",
14    "reason": "automation_owns_processing",
15    "manualHandoffId": null
16  },
17  "safety": {
18    "irreversibleBoundaryState": "unknown",
19    "finalSubmitCapable": false,
20    "requiresReviewApprovalForSubmit": false,
21    "reviewSnapshotId": null
22  }
23}

The API does not expose underlying provider-session URLs in this object.

Interpret access

FieldMeaning
statelive when a validated channel session is available, otherwise not_live.
owner.typeautomation while Collate owns the session, manual_handoff during customer handoff.
access.availableWhether a grant can be minted now.
access.supportedModesPublicly supported grant modes for the current owner.
handoff.allowedWhether the current offered handoff can be accepted. Drive creation from Authorization.nextAction, not this field alone.
safetyBoundary information to show reviewers before payer-visible actions.

During processing, live-session access is read-only. Interactive access is only available through an active manual handoff.

Create a read-only grant

1POST /v1/prior-authorizations/auth_123/live-session/access-grants
2Authorization: Bearer <API_KEY>
1{
2  "id": "rag_123",
3  "url": "https://api.trycollate.ai/runtime/access/rag_123",
4  "expiresAt": "2026-05-22T18:30:00Z"
5}

Opening a grant validates the current claim and redirects to the live channel view. Grant URLs are bearer capabilities; store them only in memory and return them only to the authenticated user who needs access.

Handle unavailable sessions

Creating a grant returns 409 live_session_not_available when there is no valid read-only channel session. The error details include a reason, such as:

  • no_active_channel_session
  • live_view_not_available
  • portal_claim_not_available
  • portal_claim_expired
  • channel_session_lost

Read the authorization and live session again before retrying. Do not treat a lost live session as payer truth; the authorization remains the source of receipt, decision, and outcome.