Connecting accounts

Your users connect their networks from your app, under your brand. They never share credentials and you never store tokens.

The flow

Your server calls GET /v1/connect/{platform} with the profileId and your app’s redirectUrl.
You redirect the user to the returned url. They authorize the network with their account.
Marsial sends them back to your redirectUrl with the outcome in the query.

curl "https://api.marsial.dev/v1/connect/linkedin?profileId=prf_8f2k4d&redirectUrl=https%3A%2F%2Fapp.acme.com%2Fconnected" \
  -H "Authorization: Bearer $MARSIAL_API_KEY"

const res = await fetch('https://api.marsial.dev/v1/connect/linkedin?profileId=prf_8f2k4d&redirectUrl=https%3A%2F%2Fapp.acme.com%2Fconnected', {
  headers: {
    Authorization: `Bearer ${process.env.MARSIAL_API_KEY}`,
  },
});
const { data } = await res.json();

import os, requests

res = requests.get(
    "https://api.marsial.dev/v1/connect/linkedin?profileId=prf_8f2k4d&redirectUrl=https%3A%2F%2Fapp.acme.com%2Fconnected",
    headers={"Authorization": f"Bearer {os.environ['MARSIAL_API_KEY']}"},
)
data = res.json()["data"]

What reaches your redirectUrl

Outcome	Parameters
Connected	`connected=<platform>`, `accountId=acc_…` and, when the network gives one, `username`
Always	`profileId`: the profile it was connected to
Needs a pick	`select=<sessionId>` and `platform`. See the next step.
Error	`error=<code>`, `platform`, `error_message` and `is_user_fixable` (`true` when the user can try again)

Picking a page, organization or board

Some networks connect something specific inside the user’s account. They come back with select and your app shows the list to pick from:

Network	What is picked
Facebook	The page
LinkedIn	Their personal profile or an organization they manage
Pinterest	The default board
Google Business	The location
Snapchat	The public profile
Slack	The channel
WhatsApp	The number, when the account has several

Bluesky and Discord do not use plain OAuth, but you need nothing different: Marsial’s connection screen asks the user for what it needs (Bluesky’s app password or the Discord channel) and comes back to your redirectUrl with connected. Slack comes back with select=<sessionId> to pick the channel, like Facebook or LinkedIn; a private channel needs the app invited first (/invite).

Sites (WordPress, Shopify, Wix and Webflow) connect here too, with two differences: Shopify needs shop and self-hosted WordPress connects with POST /v1/connect/wordpress. It is all in Blogs.

List the options

curl "https://api.marsial.dev/v1/connect/sessions/cs_5t2y8u/options" \
  -H "Authorization: Bearer $MARSIAL_API_KEY"

const res = await fetch('https://api.marsial.dev/v1/connect/sessions/cs_5t2y8u/options', {
  headers: {
    Authorization: `Bearer ${process.env.MARSIAL_API_KEY}`,
  },
});
const { data } = await res.json();

import os, requests

res = requests.get(
    "https://api.marsial.dev/v1/connect/sessions/cs_5t2y8u/options",
    headers={"Authorization": f"Bearer {os.environ['MARSIAL_API_KEY']}"},
)
data = res.json()["data"]

{
  "data": {
    "platform": "facebook",
    "options": [
      { "id": "1042…", "name": "Acme Store", "detail": "@acmestore" },
      { "id": "2210…", "name": "Acme Outlet", "detail": "Clothing store" }
    ]
  }
}

Send the pick

curl -X POST "https://api.marsial.dev/v1/connect/sessions/cs_5t2y8u/select" \
  -H "Authorization: Bearer $MARSIAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "optionId": "1042…"
  }'

const res = await fetch('https://api.marsial.dev/v1/connect/sessions/cs_5t2y8u/select', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.MARSIAL_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "optionId": "1042…"
  }),
});
const { data } = await res.json();

import os, requests

res = requests.post(
    "https://api.marsial.dev/v1/connect/sessions/cs_5t2y8u/select",
    headers={"Authorization": f"Bearer {os.environ['MARSIAL_API_KEY']}"},
    json={
        "optionId": "1042…"
    },
)
data = res.json()["data"]

It returns the connected account (201). Sessions expire after one hour.

Available networks

instagram, facebook, tiktok, youtube, linkedin, x, threads, bluesky, pinterest, reddit, google-business, discord and snapchat. Telegram is coming soon.

Listing and watching accounts

curl "https://api.marsial.dev/v1/accounts?profileId=prf_8f2k4d" \
  -H "Authorization: Bearer $MARSIAL_API_KEY"

const res = await fetch('https://api.marsial.dev/v1/accounts?profileId=prf_8f2k4d', {
  headers: {
    Authorization: `Bearer ${process.env.MARSIAL_API_KEY}`,
  },
});
const { data } = await res.json();

import os, requests

res = requests.get(
    "https://api.marsial.dev/v1/accounts?profileId=prf_8f2k4d",
    headers={"Authorization": f"Bearer {os.environ['MARSIAL_API_KEY']}"},
)
data = res.json()["data"]

Each account has a status: active, needs_reconnection (the token expired or the user removed permissions) or disconnected. To check right now whether they can post, use GET /v1/accounts/health. If an account needs reconnecting, run the flow again with the same network and profile.