Quickstart: profile → connect → publish

What you will build

Social Relay is a multi-tenant social publishing API. Your SaaS is a platform account with a prepaid token wallet and one or more applications (product isolation units). API keys, profiles, and webhooks bind to an application—so Timely and SoundCloud under the same buyer never share customers. Each end customer is a profile under an app; profiles connect supported network accounts (Facebook Pages, Page-linked Instagram professional accounts, LinkedIn personal profiles, Bluesky, Mastodon), then publish through one REST API.

This quickstart uses the production API host and curl. Replace secrets with values from your secret manager—never from a browser.

Prerequisites

You need a Social Relay platform account (sign up at socialrelay.dev/dashboard). Signup creates a Default application and shows an app-scoped API key once. For production multi-product setups, create a named application (Applications workspace) and mint keys under that app.

• API base: https://api.socialrelay.dev
• OpenAPI: https://api.socialrelay.dev/api/v1/openapi.json
• OAuth callback (production): https://api.socialrelay.dev/api/v1/connect/oauth/callback
• Server-side runtime that can hold the sk_live_ key for one application

1. Authenticate

Every product call uses Authorization: Bearer <application_api_key>. Create and rotate keys under Dashboard → Applications → API keys (select the app first). GET /me returns application context and scoped counts. Dashboard human login is email/password (optional TOTP)—not the API key in the browser.

curl -sS https://api.socialrelay.dev/api/v1/me \
  -H "Authorization: Bearer $SOCIAL_RELAY_API_KEY"

2. Create a profile

Create one profile per end customer, brand, or location under the key’s application. Optional externalId stores your CRM/org id and must be unique per application (not across the whole platform).

curl -sS -X POST https://api.socialrelay.dev/api/v1/profiles \
  -H "Authorization: Bearer $SOCIAL_RELAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title":"Acme Bakery","externalId":"org_100"}'

3. Hosted connect

Start a connect session for the profile. Open connectUrl for the end user (or iframe/redirect in your product). Prefer requesting only the networks you need (e.g. facebook + linkedin). Multi-network sessions link each network independently—if one fails after Facebook succeeds, treat it as partial and re-run connect for the remaining networks.

Live Meta/LinkedIn OAuth is enabled when app credentials are configured; otherwise sandbox mode completes the flow for early UX work.

curl -sS -X POST https://api.socialrelay.dev/api/v1/profiles/PROFILE_ID/connect/sessions \
  -H "Authorization: Bearer $SOCIAL_RELAY_API_KEY" \
  -H "X-Profile-Id: PROFILE_ID" \
  -H "Content-Type: application/json" \
  -d '{"platforms":["facebook","linkedin"],"successUrl":"https://your.app/done","cancelUrl":"https://your.app/cancel"}'

4. Validate then publish

Call validate before publish in production UIs. Publish requires Idempotency-Key (8–128 characters). Each target network is a leg billed as posts.publish_leg when attempted.

curl -sS -X POST https://api.socialrelay.dev/api/v1/posts \
  -H "Authorization: Bearer $SOCIAL_RELAY_API_KEY" \
  -H "X-Profile-Id: PROFILE_ID" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"text":"Hello from Social Relay","platforms":["linkedin"]}'

5. Status and webhooks

GET /api/v1/posts/{id} returns status and legs (succeeded, failed, partial). Prefer application-scoped webhooks for async outcomes—list/get of posts and webhooks are free; only create and publish actions debit tokens.

• Register webhooks with POST /api/v1/webhooks (same application as the key)
• Verify X-Social-Restapi-Signature on the raw body
• Retry failed legs with POST /api/v1/posts/{id}/retry

Next guides

Deepen with Authentication, Hosted connect, Publishing posts, Webhooks, Tokens and rate card, and per-network media guidelines linked from the Guides index.