Callbacks and token lifecycle

Brokerr uses generic source and target auth resources rather than one API route per provider. For either sources or targets, the lifecycle includes start, status/claim, complete when required, cancel, and disconnect operations under the /api/v2 instance resources.

Provider callback URLs are owned either by the hosted gateway or by the custom application flow displayed in the target editor. Use the exact value shown for that mode. The hosted gateway’s /v1/callback/... path is its protocol version, not an inactive Brokerr sync API.

Hosted states

Typical UI states are disconnected, pending, ready/claiming, connected, failed, canceled, or expired. Polling a pending session does not expose tokens. Once the bundle is stored locally and acknowledged, the gateway can no longer claim it again.

Local storage

Plex tokens, target access tokens, account/session data, and hosted refresh handles are encrypted with AES-256-GCM. Authenticated additional data binds each ciphertext to its credential scope, owner, and key name so an encrypted value cannot be safely moved to another row.

Automatic refresh

Targets may implement an optional refresh contract. Letterboxd currently does: before a run, an expiring access token is refreshed through the gateway and the rotated access/refresh credentials are stored atomically. Failed refresh leaves the instance disconnected or reports a reconnect requirement rather than using an invalid token for a long run.

Cancel a pending flow when the browser was closed or the wrong account was selected. Disconnect after revoking provider access, and revoke/reconnect if a credential may have been exposed.