In short
Social Relay product routes authenticate with Authorization: Bearer <application_api_key>. Keys bind to one application. Customer-scoped routes require X-Profile-Id; restricted keys may use X-Profile-Grant. POST /api/v1/posts requires Idempotency-Key. Keys stay on servers only; dashboard users sign in with email and password plus optional TOTP.
Two surfaces, two credentials
Product traffic uses application-scoped API keys (sk_live_…). Human operators of your SaaS use the platform dashboard with email/password sessions (X-Application-Id selects the Applications workspace). Social Relay staff use a separate operator console with Microsoft Entra—never your product key.
- API key → your backend → api.socialrelay.dev (one application’s data plane)
- Email/password (+ optional TOTP) → /dashboard → Applications for keys, profiles, webhooks
- Never put sk_live_ keys in SPAs, mobile apps, or public repos
Applications and API keys
A platform holds the prepaid token wallet. An application is a product isolation unit (e.g. Timely vs SoundCloud). Keys, profiles, and webhooks bind to one application. Secrets are hashed at rest; plaintext is shown once. Soft-revoke with POST …/keys/{id}/revoke; hard-delete with DELETE …/keys/{id}. Scopes: app_admin (all profiles in the app) or restricted (allowlist + optional X-Profile-Grant).
Rate limits are about 300 requests per minute per API key (server-enforced; may tighten). On 429, honor Retry-After.
X-Profile-Id (tenant scope)
Most post, connection, and connect routes require X-Profile-Id (or Profile-Id). The id must belong to the key’s application. Cross-app or cross-tenant profile ids return 404.
Map your customer id to profile externalId or store prf_… in your database. Never pass Customer A’s profile when acting for Customer B.
Authorization: Bearer sk_live_…
X-Profile-Id: prf_…
Idempotency-Key: 8-to-128-char-unique-string
Content-Type: application/jsonIdempotency-Key
Required on POST /api/v1/posts. Retries with the same key and same platform return the original post without double charge or double publish. Use a UUID or deterministic key per user intent.
Dashboard sessions
Status/list reads (connections, posts, webhooks) are free for API keys and the dashboard. Publish, link, validate, and webhook create still debit tokens. Prefer optional TOTP for accounts that can create API keys. Always select an Application before creating keys, profiles, or webhooks so nothing lands on Default by mistake.