Destinations & OAuth

A destination is the external place an integration writes into — a folder the customer authorizes with their own account. Photo Delivery supports Google Drive and Dropbox; the pattern generalizes.

The connect flow

1. Install creates the installation as pending_destination.
2. The customer picks a provider; the platform builds the consent URL and sends their browser to the provider’s OAuth screen.
3. The provider redirects back to the platform’s callback listener — a dedicated integration service, never the product API — which exchanges the code, provisions the root folder, and stores tokens.
4. The installation flips to active, the customer lands back on your app’s page, and the first sync is enqueued automatically.

The consent state token is single-use, provider-bound, and expires in ten minutes; a forged or replayed callback activates nothing.

Token rules

• Your code never sees a token. Refresh and access tokens are encrypted at rest; sync-side operations receive an authenticated client, and the UI bridge never carries credentials at all.
• Isolated OAuth clients. Each integration concern gets its own OAuth client — grants and revocations can never bleed between one integration’s destination and any other connection the workspace holds (providers revoke per user + client).
• Minimal provider scopes. Drive uses drive.file — the app can only touch files it created. Dropbox runs as an App-folder app.
• Reconnect replaces wholesale. Connecting again (same or a different provider) overwrites the destination; the platform best-effort revokes the replaced grant so nothing dangles.
• Dead tokens surface, not loop. A refresh rejected as invalid_grant marks the destination revoked and the UI shows “disconnected — reconnect to resume”; syncs skip instead of retrying into a wall.

Delivery semantics

Deliveries are ledgered per file with a content fingerprint, so syncs are idempotent: a re-run delivers only what’s new or changed. When a photo is deleted in Stageory, its mirrored copy is removed from the destination — and that is the only delete an integration performs.