Skip to main content
Your users connect their own social accounts themselves — they authenticate directly with each network, and you never see or store their credentials. Everything on this page is about getting them to that moment and finding out how it went. One thing is common to every route: a link session, created with Create a Link Session from your API key and a Profile-Key. Nothing is signed on your side and there is no private key in the flow.

Three Ways to Connect

Three shapes, and the first two are the same integration. Pick per flow — they are not exclusive, and plenty of integrations use the hosted page for onboarding and the widget inside the app afterwards.
The two widget rows are one integration, not two. A single init gives you both: mount frames where you want our buttons, and call popup() from your own button everywhere else. They share one session and report on the same handlers.Direct mode is the same popup without our script — for a page with a strict Content-Security-Policy, a server-rendered page, or a native app. There you open and watch the popup yourself.Not sure? Start with the hosted linking page. It needs no Max Pack and no extra parameters, and it is the fastest route to something working — moving to the widget later does not change how sessions are created.
Call Create a Link Session with the user’s Profile-Key in the header. For the hosted page that is the whole request:
cURL
You get back a url carrying a short-lived, opaque token:
Linking URL
You can also check whether a link has been opened and revoke it before it expires.
This one-minute video walks through creating a link. It predates link sessions, so it still shows a Private Key being sent — that step is no longer needed, and everything else it shows is unchanged.

Sending the Linking URL

A linking URL signs your user into their profile, so treat it like a password. Send it over a channel you trust, don’t log it, and don’t pass it on to a third party. It stays usable for its whole window, so a reload or an OAuth retry works — but send each link to one user only, and create a separate link per person.

Opening the Linking URL

Open it in a new browser tab, window, or view controller. You may control the closing or redirecting of that window.
The social networks do not allow the hosted linking page to be opened inside an iFrame, or the approved partner origin profile.ayrshare.com to be obfuscated. If you want linking to happen inside your own page, that is what the embedded widget is for: its frames are served from an Ayrshare origin and are the supported way to do it.

Knowing When It Is Done

Two signals, and you can use either:
  • Link completion events — set an origin when you create the link and the linking window posts connect:success, connect:error and connect:cancelled to your page as they happen. No polling.
  • Get a Link Session — reports completedAt, lastCompletedAt and completedNetworks. This is the signal for native apps, and the only one for Telegram, which completes out of band.

Link Expiry

A link is valid for 5 minutes by default. After that, create a new one. With the Max Pack, set expiresIn in minutes to widen that window — up to 2880 minutes (48 hours), which is the maximum the API accepts:
Expires In
A longer window is what makes emailing the link practical — a user reconnecting a dropped account can go straight from your email to the network, without visiting your app first.
Review with your security team how long a link should stay alive. A longer window is a longer period in which an intercepted link still works. If one gets out, you can revoke it rather than waiting for it to expire.

Profile Key

The Profile-Key identifies which User Profile the link is for. Find it in the Ayrshare developer dashboard by switching to that profile.
The Private Key is no longer used. Links are not signed, so there is nothing to read from a file or paste into your code. The legacy privateKey parameter is still accepted and ignored, so existing integrations keep working, and the private.key file in your Integration Package can be left unused.

Switching Profiles

If a profile is already signed in, opening another profile’s link does not switch profiles — that is deliberate, and it keeps the experience fast for a user who is already there. To force a switch, see Automatic Logout of a Profile Session. Instagram accounts can be linked in two ways: directly with Instagram Login, or via a connected Facebook Page. Which flow starts when a user clicks the Instagram button is normally controlled by the account-wide Instagram Login setting. The instagramLinkMethod body parameter overrides that setting for a single link:
Instagram Link Method
The override applies for the life of that link, including across the Instagram/Facebook authorization redirect. A few things to know:
  • It does not change your account-wide setting or affect any other link.
  • Omit it and the account-wide setting applies, exactly as before.
  • An invalid value returns 400 listing the valid values (instagram, facebook).
  • Review the feature differences before choosing — some Instagram features, such as hashtag search and collaborations, are only available with Facebook Page authentication.

Connect Accounts Email

Ayrshare can email the link to your user for you, so they can reach their linking page without visiting your app. Pair it with a longer expiresIn — the default five minutes rarely survives an inbox.

Connect Accounts JSON

Every field inside email is required. A missing one fails the send.
Example Contact Email Request
expiresIn is a top-level parameter, not part of the email object. Nested inside email it is ignored, and your user gets a link that expires in five minutes.
The response reports the outcome in emailSent:
Example Contact Email Response
A send failure does not come back as emailSent: false — it returns code: 333 instead. So false means no email was requested.

Connect Accounts Email Example

Here is an example of the email that opens the social linking page: Connect Accounts email The email comes from: Social Connect Hub <connect@socialconnecthub.com>

Mobile Apps

Open the linking URL in the system browser, never an embedded webview: Google rejects sign-in in one with disallowed_useragent, and Meta blocks it outright. Your user would see the network’s own error page, and nothing on your side fixes it.
  • iOSASWebAuthenticationSession, or SFSafariViewController.
  • Android — Chrome Custom Tabs.
Because a native app has no browser window to post events to, get the result from Get a Link Session instead. Set origin to your custom scheme (myapp://connected) so the page has a way back into your app.

Mobile Code Examples

Replace linkingURL with the url returned from Create a Link Session.

Testing

It is recommended to first create a link in Postman. Your Integration Package — on the Primary Profile API Key page of the dashboard — includes a sample Postman config. Import it, fill in your Profile Key in the profileKey body field, and click Send. The sample config still pre-fills privateKey and domain. privateKey is ignored, and you can clear domain unless your account has more than one linking domain. You can also generate the code from Postman.

Bubble.io

Bubble linking URL

Legacy: generateJWT

Generate a Linking URL (generateJWT) does the same job and is deprecated — fully supported, no removal date, and unchanged for links you have already handed out. Its own page documents its parameters, including the three that are now accepted and ignored.Both endpoints run the same validator, so everything on this page applies to either. The one difference worth knowing when you migrate: generateJWT tolerates three things Create a Link Session rejects — an unrecognised allowedSocial network, a lone X credential, and a non-string redirect.