tebarDocs
GuidePlatformsDevelopersAPI ReferenceChangelog

Headless connect

Clients connect their social accounts straight from your site or app, without seeing a Tebar page. Included in the Agency plan.

A regular connect link takes the client to a Tebar page first, then to the platform's login. With headless connect, the client starts on your site or app, logs in to Instagram, Threads, TikTok, or another platform directly, then comes back to your site. The client never sees a Tebar page.

It suits agencies and resellers who want onboarding to feel like part of their own service.

How it works

  1. Your app makes a connect link for the client's profile through the API.
  2. The client presses a button on your site, such as Connect Instagram, and goes straight to the platform's login.
  3. The client logs in and grants access. The account joins the profile you chose.
  4. The client comes back to redirect_url on your site, with the outcome (connected, declined, or failed).

Who can use it

  • Agency plan: available right away, no request needed. See Plans.
  • Other paid plans: contact support to ask for approval.
  • Tebar can stop this access, on the Agency plan too, for example when many clients decline at the consent screen or report it.

Required: tell your clients about Tebar

The consent screen of Instagram, Facebook, TikTok, and the other platforms always names the app Tebar. Before sending clients there, explain that their account connects through Tebar so they aren't surprised or decline. This is a condition in the Terms, and you may not disguise or hide Tebar's role.

Before you start

Register your site's domain as a redirect domain, as for a regular connect link. See Connect link.

Send headless: true and redirect_url:

curl -X POST https://api.tebar.app/v1/profiles/client-42/connect-links \
  -H "Authorization: Bearer tb_live_xxx" -H "Content-Type: application/json" \
  -d '{ "redirect_url": "https://app.example.com/tebar/done", "headless": true, "platforms": ["instagram"] }'
{
  "url": "https://publish.tebar.app/connect/s/1z35fNMp.",
  "profile_id": "9d09.",
  "expires_at": "2026-10-20T12:30:00.000Z",
  "start_urls": { "instagram": "https://api.tebar.app/connect-links/1z35fNMp./start/instagram" }
}
  • Send the client's browser to start_urls[platform] as a full navigation, never inside an iframe.
  • start_urls only lists platforms your account can connect right now. If none can, the request answers 422 platform_not_supported.
  • redirect_url is required (400 redirect_url_required).
  • A Facebook login connects every Page the client grants in Meta's dialog (the ones that can be posted to), with no Page picker.

The outcome on your site

Every outcome comes back to redirect_url, an expired or used link included, with the same status and error parameters as a regular connect link. Newly connected accounts are also sent through webhooks if you use them.

When access stops

Without the Agency plan or approval, making a link answers 403 headless_not_approved. If approval is taken back, Tebar blocks access, or the Agency plan ends, links already made stop too, including a flow already at the platform. The client comes back to your site with error=headless_not_approved. Regular connect links (through Tebar's page) keep working.

On this page