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.
Example Workflow
A common workflow is to make two endpoint calls from your app or platform. First create a new Ayrshare profile and then generate the JWT URL to display the social linkage page to your user.
After your user links their social media accounts, you will be able to post to and manage their accounts via the API.
Create an Ayrshare User Profile
During your onboarding as a Business Plan client, you received a personalized integration package with important setup 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.
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.
If you want to create client profiles via the Developer Dashboard, see the overview:
Manage User Profiles in Dashboard
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.
Please use the /profiles/generateJWT 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 /generateJWT 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.
or
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 /generateJWT endpoint.
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.
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
Please see here for more details of the user experience:
User Integration
Once your user set ups their social media links, you will be able to begin posting on their behalf using the /post and /profile endpoints.
Post
Profiles
Multiple Sets of Social Accounts
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 accomplish this in Ayrshare by following these steps:
- Create two separate User Profiles within the Ayrshare system for each user or client.
- Each User Profile will have its own unique Profile Key, returned from the create User Profile endpoint.
- Title or tag each User Profile, using the create or update User Profile endpoints, to identify which social media accounts they are associated with (e.g., “Facebook Page A” and “Facebook Page B”).
- In your own system, associate both Profile Keys with the respective user or client.
When you want to post content to a specific social media account, such as Facebook Page A, use the Profile Key associated with the User Profile tagged with “Facebook Page A.” Similarly, when you want to retrieve analytics for Facebook Page B, use the Profile Key associated with the User Profile tagged “Facebook Page B.”
By creating two 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 allows for targeted posting and analytics retrieval for each specific account.