API Integration with Single Sign On

How to integrate Ayrshare's API and SSO into the social account linkage page.

An important part of the Business Plan integration consists of creating new profile accounts in Ayrshare for your users or clients and allowing your user to link their social networks.

An Ayrshare team member will work with you during this process.

Example Workflow

A common workflow is to make two endpoint calls from your app or platform. 1) create a new Ayrshare profile and 2) 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

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

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 mange their account. You should store it in a secure location.

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

Single Sign On with a JWT Authentication Token

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

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.

Generate a JWT Example

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.

If you prefer not to generate your own JWT, you can use the /profiles/generateJWT endpoint to have Ayrshare create the token:

The following example in Node.js (Javascript) uses the json web token package. If you use another language see libraries for JWT signing:

const jwt = require("jsonwebtoken");
const fs = require("fs");
const API_KEY = "Your API Key";
const PROFILE_KEY = "Client Profile Key";
const privateKey = fs.readFileSync("./private.key", "utf8"); // to sign JWT
const payload = {
apiKey: API_KEY,
profileKey: PROFILE_KEY,
};
// Token signing options
const signOptions = {
issuer: "Issuer Domain We Provide You",
subject: "[email protected]",
audience: "https://profile.ayrshare.com",
expiresIn: "5m",
algorithm:"RS256"
};
// The token to be passed during SSO
const token = jwt.sign(payload, privateKey, signOptions);
  • You can create your own 1024 bit private/public key or Ayrshare can provide one once you activate your Business Membership.

  • The apiKey is the API Key of your primary account. It will be the same for every call. Obtain the key by logging in to the Ayrshare Developer Dashboard with your primary email and going to the API Key page.

  • The profileKey is the Profile Key of your user. Pass the profile key of the user you want to single sign on into Ayrshare. Profiles can be created with the /profiles endpoint or via the Ayrshare Developer Dashboard under Profile Key.

  • The issuer is the domain we provide you during setup and is the same for every call.

  • The subject is always [email protected]

  • The audience is the app.ayrshare.com.

  • The expiresIn is always 5m and algorithm is always RS256. NOTE: the JWT token is only valid for 5 minutes, so we suggest regenerating it every time.

A signed token is created and sent as a parameter to Ayrshare for SSO.

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

Passing the Token for SSO

The token is passed as a URL parameter. From your app open in a new tab:

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

Where domain id is your domain identified (provided to you by Ayrshare during setup) and jwt token is the token created above. This is often done from a button or link on your site.

Your client will be single signed on into the Ayrshare app and be brought to the Social Media Accounts set up page.

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 have multiple profiles they often access, you can include the URL parameter logout=true. This forces a logout and then logs in the new profile. Warning, this causes a delay of a few seconds for the user, so unless you need it, we suggest not forcing a logout.

Generating SSO URL Example

An example of generating the JWT token internally - instead of using the /profiles/generateJWT endpoint - and constructing the SSO URL.

const fs = require("fs");
const jwt = require("jsonwebtoken");
const API_KEY = "Your API Key";
const PROFILE_KEY = "Client Profile Key";
const generateToken = (privateKey, signOptions) => {
const payload = {
apiKey: API_KEY,
profileKey: PROFILE_KEY,
};
// Get the JWT token
const token = jwt.sign(payload, privateKey, signOptions);
return token;
};
const generateUrl = () => {
const domain = "Domain Provided in Set Up Guide";
const signOptions = {"Provided in Set Up Guide"};
const privateKey = fs.readFileSync("./private.key","utf8");
// Get the JWT Token
const token = generateToken(privateKey, signOptions);
return `https://profile.ayrshare.com?domain=${domain}&jwt=${token}`;
};
console.log(generateUrl());

Opening & Closing the SSO URL

The Social Accounts page has an "All Done" button that closes the window and returns your user to your site.

When you open the SSO URL, we recommend using JavaScript's window.open() function instead of an anchor href. The "All Done" button uses JavaScript to close the window and most browsers only allow windows opened via a script to be closed.

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

Additionally, if you want to have the Done button redirect back to your page (often useful on mobile), pass in the redirect GET parameter as a URL encoded string starting with https.

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 Done button back to close, pass the parameter redirect=null.

More Information

Please see here for more details of the user experience:

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