In short
Platforms create a hosted connect session per profile with HTTPS success and cancel URLs. End users complete Facebook, Instagram, or LinkedIn authorization on Social Relay. Production callback is https://api.socialrelay.dev/api/v1/connect/oauth/callback; sandbox completes without third-party apps for early integration.
Why hosted connect
Embedding three OAuth stacks multiplies app review, redirect URIs, and token storage risk. Social Relay owns the connect UI and encrypts network tokens at rest. Your product only starts a session and handles return URLs.
Session fields
POST /api/v1/profiles/{profileId}/connect/sessions accepts platforms[], successUrl, cancelUrl, and optional branding (logoUrl, primaryColor). Response includes sessionId, connectUrl, and expiresAt.
- successUrl / cancelUrl must be HTTPS
- Scope the session to the correct X-Profile-Id
- Send users only to the returned connectUrl host
Sandbox vs production
Sandbox mode (default until Meta/LinkedIn apps and secrets are configured on the Function App) finishes connect without real network credentials so you can prove isolation and publish paths.
Production OAuth uses the shared callback https://api.socialrelay.dev/api/v1/connect/oauth/callback. Register that URI on Meta and LinkedIn developer apps. Tokens never appear as platform API key material.
Asset picker
When a user manages multiple Facebook Pages, Social Relay presents a selection step so the connection binds the correct Page under the profile.
Billing note
Successful link completion debits connection.linked (5 tokens) per network linked, per the rate card version 2026-08-04.