> ## Documentation Index
> Fetch the complete documentation index at: https://mcp.shipcontent.com/llms.txt
> Use this file to discover all available pages before exploring further.

---
title: Connections
description: The connection lifecycle of supported channels, from the agent handoff to the owner consent, the saved status and the disconnect.
section: contracts
order: 45
status: implemented
mode: both
reviewed: 2026-11-19
sources: [db/migrations/20261119T0440_facebook_token_refresh.sql, db/migrations/20261112T2130_agent_instagram_destination.sql, db/billing.sql, src/lib/server/tiktok/TikTokAccounts.ts, src/lib/server/tiktok/TikTokAccountsPrivateDatabase.ts, db/tiktok.sql, src/lib/server/owner/connections-overview.ts, src/lib/social/connections.ts, src/lib/youtube/youtube.ts, src/lib/server/youtube/YouTubeService.ts, src/lib/server/advertising/connections.ts, src/lib/server/advertising/service.ts, src/lib/docs/handoffs.ts, db/publishing.sql, db/instagram.sql, docs/tiktok-mcp.md, docs/instagram-connection-contract.md, src/lib/server/instagram/instagram-agent-tools.ts, src/lib/server/instagram/InstagramOAuthProvider.ts, src/lib/server/database/queries.ts, src/lib/mcp/agent-tools.ts, src/lib/server/mcp/AgentMcp.ts, src/lib/social/connect-path.ts, src/lib/server/social/connect-start.ts, src/lib/server/lifecycle/MetaErasure.ts, src/lib/server/lifecycle/MetaErasureWorker.ts, scripts/meta-runtime-logins.ts, src/app/data-deletion/[[...token]]/route.ts, src/lib/server/lifecycle/MetaErasureStatus.ts, src/lib/server/lifecycle/MetaErasureStatusDatabase.ts, src/lib/server/lifecycle/meta-erasure-status-response.ts, db/meta.sql, .env.example, src/lib/server/lifecycle/meta-lifecycle-route.ts, src/lib/server/lifecycle/meta-signed-request.ts, src/lib/server/lifecycle/MetaLifecycleCallback.ts]
tools: [start_instagram_connection, get_instagram_connection, list_instagram_connections, ads_start_connection, ads_list_connections, ads_get_connection, ads_list_advertisers]
next: [/docs/channels/overview]
---
Provider connections start in the owner's browser. Agent tools return protected handoff URLs and saved metadata; they do not return OAuth state, tokens, or provider credentials.

Instagram, X, YouTube, TikTok, Facebook and Threads share one start link: `/connect/{provider}` with the workspace ID and a return page (`setup` or `connections`). The owner opens it and goes straight to the provider. The link starts an authorization and changes nothing until the owner approves at the provider. The provider state stores the return page as one of these two words, never as a URL.

`get_onboarding_status.socialConnections` reports saved social identities for
the selected workspace. Each row names its provider. One connected row can
exist per workspace and provider. The row does not prove current access or a
publishing destination. Instagram has the owner selection flow below. TikTok publishing is in development. X customer publishing is available when configured. TikTok Ads access stays
in the separate advertiser connection flow.

## Instagram

Call `start_instagram_connection` with one stable `requestId`, then give `connectionUrl` to the owner. The owner opens it and goes straight to Instagram to connect a professional account. An agent's request stays bound to its grant. Use `get_instagram_connection` or `list_instagram_connections` to resume and read the current lifecycle. Connected status does not prove video readiness or authorize publication.

The server checks Meta's returned grants and exact account IDs before it saves the connection. An unconfirmed result stays unconfirmed until the owner cancels the request and starts a new one.

For a post, `prepare_instagram_destination` opens `/posts/review` so the owner can select the account. Then call `prepare_instagram_readiness` and read `get_instagram_readiness`. A saved readiness result can become stale after media, draft, account, credential, or authority changes.

Updated 2026-11-12: with Publish and an `automatic` Reel, the agent does not use these two steps. It calls `publish_instagram_reel` or `prepare_post_schedule`, which use the one connected account; see [Instagram](/docs/channels/instagram#automatic-publishing). `prepare_instagram_readiness` still needs the account that the owner selected.

Instagram insights renewal is a separate optional grant. Denying it keeps a valid existing publishing connection. Stored insight permission does not prove a successful dashboard read.

## Facebook Pages and Threads

The owner connects these channels from Connections. Facebook returns authorized Page choices and requires an explicit Page selection. Threads verifies its own product identity and requires owner confirmation before a reconnect can replace the selected profile. They have no MCP start or publishing tool; `get_onboarding_status.channels.startTool` is null. Use the owner Connect link.

Facebook saves the end date of its User access, and the worker refreshes that access automatically while it ends in 30 days or less. Updated 2026-11-19: a Facebook connection whose access has ended, or whose saved credential is missing, reads `reconnect-required` in `get_onboarding_status` (`channels[].state` and `socialConnections[].status`). It no longer reads `connected`. A working connection reports the end date in `socialConnections[].expiresAt`. When the access ended, the owner uses the Facebook Connect link again. See [Access lifetime and refresh](/docs/channels/facebook#access-lifetime-and-refresh).

Threads token expiry and data-access grant expiry are separate. Either expiry requires reconnect; a valid token does not extend an expired private-profile grant. Local disconnect removes app authority and fences late connection/refresh results. It keeps native posts. Provider-side revocation and provider-data erasure are separate flows. See [Facebook Pages](/docs/channels/facebook) and [Threads](/docs/channels/threads).

Updated October 11, 2026: the internal Meta erasure service requires a current authenticated owner and an exact saved product/app/connection authority set across affected workspaces, including each server-generated consent generation. Reusing a request or connection UUID cannot make an old binding select fresh consent. Its app and worker database roles are separate. It has no owner button or MCP tool. Updated 2026-10-12: six signed Meta callback routes start deauthorization or deletion; see [Instagram](/docs/channels/instagram), [Facebook Pages](/docs/channels/facebook) and [Threads](/docs/channels/threads). A verified deauthorization disconnects every matching connection and keeps history. A verified deletion request erases the subject for every owner that saved it, and one status link completes after the last owner. Live Meta acceptance remains unproved. A saved opaque token can open `/data-deletion/{token}`. This read-only page shows Pending, Processing or Completed through a separate status-only database role. It sends no account details, IDs, dates or token to page content, external assets or analytics. Unknown, malformed, expired and unavailable links show the same page. Links expire 30 days after completion. Reads cannot start or reopen deletion. Native callback acceptance remains unproved.

The approved erasure policy keeps independent owner uploads, draft text and business facts. Provider credentials, identities, avatars, cached metrics and result links are removed in the selected scope. Cached follow-up data cannot restore those fields after erasure or source removal. Manual owner metrics and valid unrelated evidence remain. An in-flight provider request can still finish; its late provider fields must not restore erased data or authorize a second send. A Reel finish acknowledgement alone keeps unknown status until native publication is proved. Neutral no-retry evidence lasts only while its retained owner post exists. Internal status needs current authentication and the opaque token; the token holder can read only neutral status, not the original owner's identity. It expires 30 days after completion; expiry cannot reopen work. Native social posts remain at the provider.

Updated 2026-10-16: erasure also covers scheduled posts. A pending schedule of an erased Instagram, Facebook or Threads account is cancelled and cannot send. The saved copy of its content and account is removed. A publication that was already created follows the rules above.

Updated 2026-10-18: the saved text generation records no longer exist, so erasure has no step for them.

Operator configuration uses `SHIPCONTENT_META_LIFECYCLE_DATABASE_URL` on the app and `SHIPCONTENT_META_LIFECYCLE_WORKER_DATABASE_URL` on the worker. The separate NOINHERIT logins have only `shipcontent_meta_lifecycle` or `shipcontent_meta_lifecycle_worker`, with no direct table access. Keep them separate from owner, agent and provider logins. Provision with `SHIPCONTENT_BOOTSTRAP_META_LIFECYCLE_PASSWORD` and `SHIPCONTENT_BOOTSTRAP_META_LIFECYCLE_WORKER_PASSWORD` plus the four Facebook/Threads bootstrap passwords. The worker cannot plan or start erasure.

## TikTok Ads

`ads_start_connection` returns `/advertising/connect`; the owner authorizes TikTok and selects advertisers. Use `ads_list_connections`, `ads_get_connection`, and `ads_list_advertisers` to inspect saved access. Provider reads need a current connection; saved status alone is not a live access check.

Only the owner can change connection state. `connections:write` is a defined server action, but it is not issued to the MCP client through the current owner grant options. Do not ask the owner for credentials in chat.

## YouTube

Use `start_youtube_connection` for the owner channel handoff and `get_youtube_status` for saved progress. The first channel is saved when Google returns it. A reconnect that returns a different channel waits for the owner's confirmation. One YouTube connection can coexist with Instagram. Disconnect removes local credentials and stops new uploads; it does not undo uploaded videos. See [YouTube](/docs/channels/youtube).

The TikTok organic channel is listed as **Not configured**. Its draft contract is available, but account authorization is in development. The existing advertiser connection cannot supply an organic publishing destination.

## TikTok Accounts

The owner opens `/connect/tiktok` from Connections to authorize one Personal/creator or Business account, subject to TikTok access. The server saves inspected app/account identity and granted scopes with encrypted tokens. A different reconnect account waits for confirmation. Agents can read safe metadata and use granted read capabilities; they cannot confirm or disconnect an account, or obtain its credentials. Disconnect stops local access and preserves saved media and posts. See [TikTok setup](/docs/channels/tiktok#operator-setup).

Updated October 11, 2026: the operator provisions the separate public status login with `SHIPCONTENT_BOOTSTRAP_META_STATUS_PASSWORD` and sets its runtime URL as `SHIPCONTENT_META_STATUS_DATABASE_URL` on the app only. Keep the bootstrap password outside app and worker services. The status role has no table, provider or lifecycle authority.

Updated 2026-10-16: In enforce mode, the final Instagram, X, YouTube, TikTok, Facebook or Threads save checks the owner's connected-channel limit across active owner workspaces. Starting OAuth or listing Facebook Page choices does not use capacity. A connected replacement uses its net increase; a reconnect-required connection uses a new place. Refusal preserves the previous saved connection and credentials. Disconnect and erasure can reduce usage above the limit.
