API Integration for Business

Allow Your Users to Connect Their Social Media Accounts

An important part of the Business Plan integration consists of creating new profile accounts in Ayrshare for your users or clients and allowing your users to link their social networks with the social linking page. Each of your users is set up as an Ayrshare user profile. A user profile gets one connection to each social network.

Integration Workflow

To integrate Ayrshare into your application, you’ll need to make two API calls:

1. Call the Create Profiles endpoint to create a new Ayrshare profile for your user.
2. Call the Generate JWT endpoint to get a JWT URL.

The JWT URL allows your user to securely access the social media linking page through single sign-on authentication. You’ll display this page in a new tab, window, or view controller to let users connect their social media accounts.

After your user links their social media accounts, you will be able to publish posts, get analytics, and manage their accounts via the API.

For security reasons, social media platforms require users to authenticate through their browser, which cannot be done through backend server calls. This ensures your users can safely connect their social media accounts by logging in directly with each platform’s official login page. Social networks restrict authentication to happen only through their authorized partner domains, such as Ayrshare. They also block iFrames, which means you cannot embed or display the Ayrshare linking page within an iFrame on your site.

Create an Ayrshare User Profile

Create a Profile with the API

When a new user registers with your system or when your client clicks the social network link in your app, create a new Ayrshare profile account by calling the /profiles/create-profile RESTful endpoint, or using the NPM or PyPi packages.

Profiles

Returned from this call will be your user’s PROFILE KEY. This key will be used to post on your user’s behalf and to manage their account. You should store it in a secure location.

Create a Profile with the Dashboard

If you want to create client profiles via the Developer Dashboard, see the overview:

Manage User Profiles in Dashboard

Integration Package

During your onboarding as a Business Plan client, you received a personalized integration package with important set up and domain information, example endpoint calls, and more. Please check with your primary account holder for this information.

You may also retrieve or reset the integration package in the dashboard in the API page. Be sure to first switch to your Primary Profile.

Single Sign-On with JWT Authentication

Ayrshare uses a JWT (JSON Web Token) to authenticate your user and perform Single Sign-On to the social linking page. A JWT is a secure mechanism for passing digitally signed information and allows Ayrshare to authenticate you and your user.

Generate a JWT

Your app will construct a JWT comprised of your API Key, user Profile Key, and a few other parameters. This will be signed with your 1024-bit private key.

The JWT token is valid for 5 minutes. Please see the Max Pack for longer expire time.

Please use the Generate JWT endpoint to have Ayrshare create the token and social linking URL. Open the social linking URL in a new tab or window, allowing your users to easily link their social networks.

Alternatively, if you have your client’s social media credentials (username/password), you can link their social network yourself using Ayrshare’s Developer Dashboard.

Automatic Logout of a Profile Session

How to Automatically Logout of the Active Profile Session

If a profile is already logged in, sending a different profile’s JWT will not switch profiles. This is done to make the experience faster for already logged-in users. When testing, log out of the current profile before making an SSO call with a different profile. Signed-in profiles remain signed in until explicitly logged out.

However, if you have a business need, such as your users having multiple profiles they often access, or you want to test, include the URL parameter in the SSO URL:

logout=true

For example:

https://profile.ayrshare.com?domain=[domain id]&jwt=[jwt token]&logout=true

This forces a logout and then logs in the new profile.

Please also see the Generate JWT endpoint to automatically add the logout.

Warning: Using automatic logout causes a performance delay for your user, so unless you need it, we suggest not forcing a logout and not using it in production.

Opening & Closing the Social Linking URL

The Social Accounts page has a “Close” button that closes the window and returns your user to your site.

Opening the Social Linking URL

When you open the social linking URL, we recommend using JavaScript’s window.open() function instead of an anchor href. The “Close” button uses JavaScript to close the window, and most browsers only allow windows opened via a script to be closed. You can use the following sample code on your website to launch the social linkage window.

Window Open

<div onclick="window.open('https://profile.ayrshare.com?domain...', '_blank')">
  Link Social Networks
</div>

or

Window Open Function

<button onclick="openNewTabAndRedirect()">Open New Tab and Redirect</button>
<script>
  function openNewTabAndRedirect() {
    // Open a new tab
    var newTab = window.open("https://profile.ayrshare.com?domain...");

    // Optional: Focus on the new tab
    newTab.focus();
  }
</script>

You may control the “Close’ button to either redirect the social linking tab to a page of your choosing or redirect the origin opener tab/window and close the social linking tab. This can be done using the redirect parameter and adding origin=true to the query parameters of the redirect URL. Please see Generate JWT endpoint for more details.

Redirecting When Closing

Additionally, if you want to have the Close button redirect back to your page (often useful on mobile), pass in the redirect GET parameter as a URL encoded string starting with https. Please see the Generate JWT endpoint parameters for more details.

JWT URL

https://profile.ayrshare.com?domain=[domain id]&jwt=[jwt token]&redirect=https%3A%2F%2Fmywebsite.com

The redirect will be saved for that profile and used in subsequent SSO calls even if the redirect parameter is not passed. To reset the Close button back to close, pass the parameter redirect=null.

More Information

User Linking or Unlinking Notifications

When a user links or unlinks a social network, you can receive a notification via webhook. Please see the Social Action Webhooks page for more information.

You may also use the user endpoint to get the connected social networks for a user profile.

Multiple Sets of Social Accounts

Overview

Each User Profile has a set of social media accounts and can make one connection to each social network. If your users or clients have multiple sets of social media accounts, such as two Facebook Pages, two Instagram accounts, and two YouTube channels, you can manage these multiple sets of social media accounts by following these steps:

1. Create multiple User Profiles - Create separate User Profiles within the Ayrshare system for each set of social accounts your user or client needs to manage.

2. Store unique Profile Keys - Each User Profile will have its own unique Profile Key, returned from the create User Profile endpoint.

3. Label your profiles - Title or tag each User Profile to clearly identify which social media accounts they’re associated with (e.g., “Facebook Page A” and “Facebook Page B”).

4. Map in your database - In your own system, associate all relevant Profile Keys with the respective user or client.

5. Use appropriate Profile Key - When posting content or retrieving analytics for a specific social account, use the Profile Key associated with that account. For example, to post to Facebook Page A, use the Profile Key of the User Profile connected to Facebook Page A.

Example

Let’s consider a practical scenario for multiple client accounts:

• Client: Joe’s Restaurant Chain with two locations

Joe needs separate social media accounts for each restaurant location:

Restaurant Location 1:

• Facebook Page: “Joe’s Downtown Bistro”
• Instagram: @joesdowntownbistro
• LinkedIn: Joe’s Downtown Bistro business page

Restaurant Location 2:

• Facebook Page: “Joe’s Seaside Grill”
• Instagram: @joesseasidegrill
• LinkedIn: Joe’s Seaside Grill business page

Implementation solution:

1. Create two separate User Profiles in Ayrshare:

• User Profile 1: Titled “Joe’s Downtown Bistro Accounts”
• User Profile 2: Titled “Joe’s Seaside Grill Accounts”

2. Connect the appropriate social accounts to each profile:

• Profile 1: Links the Downtown Bistro Facebook, Instagram, and LinkedIn
• Profile 2: Links the Seaside Grill Facebook, Instagram, and LinkedIn

3. Store both Profile Keys in your database, associating them with Joe’s account:

   Client: Joe's Restaurant Chain
   - Profile Key 1: abc123... (Downtown location)
   - Profile Key 2: xyz789... (Seaside location)
   

4. When posting a special menu update for the Downtown location, use Profile Key 1 in the API calls. When posting about a seafood promotion at the Seaside location, use Profile Key 2.

By creating multiple User Profiles, titling or tagging them appropriately, and associating them to a single user or client in your system, you can manage their multiple social media accounts across the same platforms using Ayrshare. This approach allows for targeted posting and analytics retrieval for each specific account.

Next Steps

Please see here for more details of the user experience:

User Integration

Once your user sets up their social media links, you will be able to begin posting on their behalf using the /post and /profile endpoints.

Post API

Profiles API