Connecting accounts

Before Reelspan can post to a network, the profile needs an account connected there. Each profile holds one account per network. There are three ways to connect one:

All three save the same kind of connection: once an account is connected, it doesn't matter how.

How each network connects

Ten networks connect with an OAuth sign-in: the account owner signs in on the network and allows Reelspan to post. The other twelve connect with credentials the owner makes on the network: a bot token, a webhook, an access token or an app password. Reelspan checks credentials with the network before saving them, and stores them encrypted.

The exact fields for each credentials network, with the names the API accepts, are on Connect with credentials.

In the dashboard

1. Open Accounts and pick the profile.
2. Click Connect next to the network.
3. For an OAuth network, sign in on the network and allow access. You come back to the Accounts page.
4. For a credentials network, a form shows the setup steps for that network and the fields to fill in.

Only workspace owners and admins can connect accounts.

Facebook: if you manage several Pages, the dashboard asks which Page to post to after you connect. You can change it later on the account's page, or choose per post with facebook_page_id.

With a connect link

Send your client a link to a hosted page where they connect their own accounts to one of your profiles. They don't need a Reelspan account and never see your API key.

curl -X POST https://api.reelspan.com/v1/connect-links \
  -H "Authorization: Bearer $REELSPAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"username": "my-brand", "platforms": ["tiktok", "instagram", "youtube"]}'

import { Reelspan } from 'reelspan';

const reelspan = new Reelspan();
const { access_url } = await reelspan.connect.link('my-brand', { platforms: ['tiktok', 'instagram', 'youtube'] });

from reelspan import Reelspan

reelspan = Reelspan()
access_url = reelspan.connect.link("my-brand", platforms=["tiktok", "instagram", "youtube"])["access_url"]

The link works for 48 hours. On the page, OAuth networks have a Connect button and credentials networks have a short form. Your logo, texts, theme and language are set on the same call; see White-label connect.

Through the API

OAuth networks

Start the sign-in with POST /v1/oauth/{platform}/start, send the person to the authorize_url it returns, and they come back to your redirect_url with the outcome in the query string.

curl -X POST https://api.reelspan.com/v1/oauth/tiktok/start \
  -H "Authorization: Bearer $REELSPAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"profile": "my-brand", "redirect_url": "https://example.com/connected"}'

const { authorize_url } = await reelspan.connect.oauthStart('tiktok', { profile: 'my-brand', redirectUrl: 'https://example.com/connected' });

authorize_url = reelspan.connect.oauth_start("tiktok", profile="my-brand", redirect_url="https://example.com/connected")["authorize_url"]

The authorize_url is good for 15 minutes and works once. When the person returns, connect_status is success, cancelled or error. The whole flow, including starting it with a connect link's token from your client's browser, is on White-label connect.

Credentials networks

Send the fields to POST /v1/accounts/{platform}. Reelspan checks them with the network and answers with the connected account.

curl -X POST https://api.reelspan.com/v1/accounts/discord \
  -H "Authorization: Bearer $REELSPAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"profile_username": "my-brand", "webhook_url": "https://discord.com/api/webhooks/123/abc"}'

await reelspan.accounts.connect('my-brand', 'discord', { webhook_url: 'https://discord.com/api/webhooks/123/abc' });

reelspan.accounts.connect("my-brand", "discord", webhook_url="https://discord.com/api/webhooks/123/abc")

Every network's fields are on Connect with credentials.

See what is connected

GET /v1/profiles/{username} lists every network in social_accounts: "" when nothing is connected, or the account's details. See Profiles.

Reconnecting

Networks sometimes sign Reelspan out: the person changed their password, removed the app's access, or a token couldn't be renewed. Reelspan notices when a post fails for that reason, and then:

• the account shows reauth_required: true in social_accounts;
• posts to that network are skipped with error_code: reauth_required until it is fixed, while the other networks still post;
• the social_account_reauth_required webhook fires, and the workspace gets a dashboard notification and an email.

To fix it, connect the same network again on the same profile, in any of the three ways. Connecting again replaces the old connection on that profile and makes it active; posts that were skipped can then be sent with Retry. For Facebook, the Page you had chosen is kept if it is still shared.

Connecting a different account on a network that already has one also replaces it: a profile never has two accounts on one network.

Disconnecting

curl -X DELETE https://api.reelspan.com/v1/accounts \
  -H "Authorization: Bearer $REELSPAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"profile_username": "my-brand", "social_platform": "tiktok"}'

await reelspan.accounts.disconnect('my-brand', 'tiktok');

reelspan.accounts.disconnect("my-brand", "tiktok")

Disconnecting deletes the stored tokens or credentials and fires the social_account_disconnected webhook. It is safe to repeat: disconnecting a network that isn't connected also answers 200. Your client can also disconnect from a connect link's page, unless the link is read-only.

Disconnecting removes Reelspan's copy of the access. To revoke it on the network's side too, remove Reelspan from the account's connected apps in that network's settings.

Scopes

Connecting and disconnecting through the API, and creating connect links, need a key with the profiles scope. See Authentication.

Features waiting for a network's approval

Some features use a permission a network grants only after it reviews Reelspan's app. They are built and in the API now. Until the network approves, they answer 403 with error_code: "permission_pending". Once approved, Reelspan switches the permission on: new connections ask for it, and accounts connected before then must reconnect once (the call answers 409 permission_reconnect until they do). GET /v1/permissions lists each one with status: "pending" or "live".

These need API access that the networks haven't opened to Reelspan's apps yet. They aren't in the API until that access exists:

• TikTok: music (trending, search, tiktok_music_*), locations (tiktok_location_*), tiktok_is_ads_only and tiktok_tto_invite_link, comments and audience insights. TikTok's public Content Posting API has none of them.
• Comments, direct messages and auto-replies on Instagram, Facebook, Threads, YouTube, TikTok and LinkedIn: each needs its network's comment or messaging permission.

A few Upload-Post fields have no counterpart in the networks' public APIs, so Reelspan doesn't offer them: YouTube allowedCountries and blockedCountries (read-only in the YouTube API), X Articles, and pinterest_ai_disclosures.