Social accounts

A brand publishes through the social accounts connected to it. Your client connects each account themselves: they log in with the platform and grant access there. You never handle their password.

You start a connect with a link from create_connect_link, and you confirm it with get_profile.

A headless link suits an app where your client never sees Native: they click "Connect Instagram" in your app, consent on Instagram, and land back in your app.

Headless links are in development. This is how they are planned to work:

1. Your backend calls create_connect_link with brandId, platform and returnUrl.
2. You send your client’s browser to the url it returns. Your backend never opens it.
3. The client logs in with the platform and grants access.
4. The browser comes back to returnUrl with status and platform added to it.
5. On selection_required, you list the client’s Pages or organisations with get_connect_options, they choose one, and you call complete_connect.
6. You call get_profile until the account’s channel is connected and readiness.canPublish is true.

Makes a single-use link your client opens to connect or reconnect a social account for one brand. It changes data, so the token needs the mcp:write scope.

• Hand the url to your client. Do not open or fetch it yourself: loading it uses it up.
• If nobody opens it, the link expires about 10 minutes after you make it. Once it is opened, the client has about 15 minutes to finish at the platform.
• The link only connects an account to this brand. It gives nobody access to the brand or the workspace.
• When a link expires, make a fresh one. A fresh link can always be made.

Bluesky is not on the platform list. It connects with an app password typed into Native’s own page, so use a link without platform for it.

With returnUrl and no platform, the link opens Native’s connect page, and its Done button takes the client to returnUrl. Native adds nothing to the URL in that case. Call get_profile to see what was connected. A brand still on Native’s older social provider gets that provider’s own connect page instead, which has no Done button.

{
  "brandId": "3f6c2a9e-8b1d-4c57-9e0a-2d4b7f1c8a63",
  "platform": "instagram",
  "returnUrl": "https://app.example.com/connect/done?client=4711"
}

{
  "url": "https://app.native.no/e/connect/q8Zt3VbN1xKc5mWp0rLs2A/go",
  "expiresAt": "2026-11-02T09:10:00.000Z",
  "singleUse": true,
  "brandId": "3f6c2a9e-8b1d-4c57-9e0a-2d4b7f1c8a63",
  "brandName": "Harbour Street Bakery",
  "platform": "instagram"
}

When a headless connect ends, Native sends the browser to returnUrl with query parameters added. status says how it ended, and platform is always there.

https://app.example.com/connect/done?client=4711&status=connected&platform=instagram
https://app.example.com/connect/done?client=4711&status=selection_required&platform=linkedin&connectToken=...
https://app.example.com/connect/done?client=4711&status=failed&platform=tiktok&error=oauth_denied

Native first removes any status, platform, connectToken or error already on your URL, then adds its own. Your other query parameters stay. So you can put your own reference to the client in returnUrl, as client=4711 does above.

If your client opens a headless link after it has expired or been used, Native still sends the browser back to returnUrl, with status=failed and error=link_expired. It does this for up to an hour after you made the link. After that, the link opens Native’s own expired-link page.

Treat error as an open set. Some codes come from Native’s social provider, and new ones can appear. Whatever the code, a fresh link is the way to try again.

After status=selection_required, lists the Pages, organisations, boards or locations the client can connect to the brand. Show them to the client and let them choose. Reading the options changes nothing, and you can call it again.

For LinkedIn, the client’s own profile comes first, with kind: "personal" and id: "__personal__".

{
  "brandId": "3f6c2a9e-8b1d-4c57-9e0a-2d4b7f1c8a63",
  "platform": "linkedin",
  "options": [
    {
      "id": "__personal__",
      "name": "Kari Nordmann",
      "kind": "personal",
      "pictureUrl": null,
      "detail": null
    },
    {
      "id": "urn:li:organization:81234567",
      "name": "Harbour Street Bakery",
      "kind": "organization",
      "pictureUrl": null,
      "detail": null
    }
  ]
}

Connects the option your client chose to the brand. It changes data, so the token needs the mcp:write scope.

It replaces any account the brand already had on that platform. Only call it with your client’s own choice.

{
  "brandId": "3f6c2a9e-8b1d-4c57-9e0a-2d4b7f1c8a63",
  "connectToken": "c2VhbGVkLWNvbm5lY3QtdG9rZW4tZXhhbXBsZQ",
  "selectionId": "urn:li:organization:81234567"
}

{
  "brandId": "3f6c2a9e-8b1d-4c57-9e0a-2d4b7f1c8a63",
  "platform": "linkedin",
  "connected": true,
  "account": {
    "displayName": "Harbour Street Bakery",
    "username": null
  }
}

get_profile shows what a brand can do right now, including each connected account and its health. After status=connected, or after complete_connect, call it once. If the account is not ready yet, call it every 10 seconds for up to 2 minutes.

The account is ready when its channel has health: "connected" and readiness.canPublish is true. A failed status needs a fresh link, not more polling.

The result data has more than this, such as brandName and generationPlatforms. Profiles has the full reference. These are the fields that tell you whether a connect worked:

{
  "readiness": {
    "canGenerate": true,
    "canPublish": true,
    "blockers": []
  },
  "channels": [
    {
      "platform": "instagram",
      "displayName": "Harbour Street Bakery",
      "username": "harbourstreetbakery",
      "profileUrl": "https://www.instagram.com/harbourstreetbakery",
      "health": "connected",
      "healthReason": null,
      "connectedAt": "2026-11-02T09:04:12.000Z",
      "tokenRefreshInDays": 58,
      "scopes": null
    }
  ],
  "storyDestinations": [
    "instagram_stories"
  ]
}

Stories have no connect link of their own. Instagram and Facebook stories publish through the Instagram and Facebook accounts, and never appear as channels.

Channel names in get_profile are lowercase, such as instagram. A post’s destinations use uppercase names, such as INSTAGRAM.

This sketch uses client, an official MCP SDK client connected with a partner token, as in Calling a tool. Make the link and send your client’s browser to it:

const brandId = "3f6c2a9e-8b1d-4c57-9e0a-2d4b7f1c8a63";

const minted = await client.callTool({
  name: "create_connect_link",
  arguments: {
    brandId,
    platform: "linkedin",
    returnUrl: "https://app.example.com/connect/done?client=4711",
  },
});
const link = (minted.structuredContent as { data: any }).data;
if (minted.isError) throw new Error(link.error.code);

// Redirect your client's browser to link.url. Never fetch it from your backend.

When the browser comes back, read status from the URL:

async function onConnectReturn(returned: URL, brandId: string) {
  const status = returned.searchParams.get("status");

  if (status === "failed") {
    // Offer a fresh link. The error parameter says why it failed.
    return { state: "failed", error: returned.searchParams.get("error") };
  }

  if (status === "selection_required") {
    const connectToken = returned.searchParams.get("connectToken") ?? "";
    const listed = await client.callTool({
      name: "get_connect_options",
      arguments: { brandId, connectToken },
    });
    const data = (listed.structuredContent as { data: any }).data;
    if (listed.isError) return { state: "failed", error: data.error.code };
    // Show data.options to your client. Keep connectToken until they choose.
    return { state: "choose", options: data.options, connectToken };
  }

  // "connected", or anything else: check the profile before you trust it.
  return { state: "check" };
}

Once your client has chosen, finish the connect. Then wait until the account can publish:

async function finishConnect(brandId: string, connectToken: string, selectionId: string) {
  const done = await client.callTool(
    {
      name: "complete_connect",
      arguments: { brandId, connectToken, selectionId },
    },
    undefined,
    { timeout: 150_000 },
  );
  const data = (done.structuredContent as { data: any }).data;
  // connect_session_expired: make a fresh link and start again.
  if (done.isError) throw new Error(data.error.code);
}

async function waitUntilPublishable(brandId: string, platform: string) {
  for (let attempt = 0; attempt < 12; attempt++) {
    const result = await client.callTool({ name: "get_profile", arguments: { brandId } });
    const profile = (result.structuredContent as { data: any }).data;
    if (result.isError) throw new Error(profile.error.code);

    const channel = profile.channels.find((c: { platform: string }) => c.platform === platform);
    if (channel?.health === "connected" && profile.readiness.canPublish) return true;

    await new Promise((resolve) => setTimeout(resolve, 10_000));
  }
  return false; // Not ready after 2 minutes: offer a fresh link.
}

Platforms take access back after a while, and people change passwords. Check channel health with get_profile once a day, and before you schedule.

A reconnect uses the same create_connect_link call as a first connect. Tell your client which account to reconnect: get_profile names it.

Every tool on this page can also return the errors any tool can: bad_request, not_found, forbidden, subscription_required, internal_error, upstream_timeout, upstream_unavailable, upstream_identity_failed, identity_provider_unavailable and upstream_<status>. create_connect_link and complete_connect can return writes_disabled. Errors explains each one.