The Business Plan is required for accessing these endpoints.
Create a User Profile
POSThttps://app.ayrshare.com/api/profiles
Create a new profile under your Primary Profile. Upon successful creation of the User Profile, the API response will include the Profile Key associated with the newly created profile. Securely store the Profile Key in your system, as it will be required to make API calls on behalf of your user.
Please note that for security reasons, the Profile Keys are only returned in two specific cases:
User Profile Creation: When a new User Profile is created.
In the Ayrshare Dashboard: You can find the Profile Key for each profile within the Ayrshare Dashboard. Switch to the User Profile and then navigate to the Profile Key page.
We recommend you securely store the Profile Key in your system.
Manage Social Networks
Please use the disableSocial field to manage (add/remove) social networks from display. Please Manage Social Accounts for more information.
Profile Keys are sensitive credentials used to authenticate and authorize access to User Profiles. It is crucial to store Profile Keys securely in your system to maintain the integrity and confidentiality of your users' data.
Avoid sharing Profile Keys publicly or exposing them in client-side code or public repositories.
Headers
Name
Type
Description
Authorization*
string
Format: Authorization: Bearer API_KEY. See Overview for more information.
Request Body
Name
Type
Description
title*
string
Title of the new profile. Must be unique. This title will be displayed on the social account linking page.
messagingActive
boolean
Set to true to active messaging for this user profile. Default: false. Messaging must be first be enabled for the account.
hideTopHeader
boolean
Hide the top header on the social accounts linkage page. Default false.
topHeader
string
Change the header on the social accounts linkage page. Currently displays: "Social Accounts for {title}" where {title} is the profile title.
disableSocial
array
Array of social networks that are disabled for this user's profile. The primary profile's list of disabled social networks takes precedence.
Available networks:twitter, facebook, instagram, linkedin, telegram, gmb, youtube, tiktok, pinterest, and reddit.
Create a new user profile as a team member by setting team: true. The email field will be used to send an invite email. See inviting a team member for details on the requirements.
email
string
A valid email address where the team member invite will be sent. Required if team: true
subHeader
string
Change the sub header on the social accounts linakge page. Currently displays "Click an icon to link a social network". Set to an empty string to remove.
Tag user profiles using an array of strings. These tags serve as an internal organizational tool to categorize and manage your user profiles effectively.
The Profile Key returned should be securely stored in your system with appropriate access controls. For security reasons, the Profile Key can't not be retrieved again via the API. However, you can retrieve the Profile Key via the dashboard.
The refId should also be stored to associate a profile to an endpoint return.
Delete a User Profile
DELETEhttps://app.ayrshare.com/api/profiles
Delete a user profile you are the owner of. Deleting a User Profile deleted all referenced and is irrevocable - cannot be undone.
Headers
Name
Type
Description
Authorization*
string
Format: Authorization: Bearer API_KEY. See Overview for more information.
Profile-Key*
string
The Profile Key of the profile to delete, returned from /create-profile. May also use the API Key found in the web dashboard.
Request Body
Name
Type
Description
title
string
Title of the User Profile to delete. Must be present if profileKey is not passed. title is case-sensitive and must match the User Profile title.
Update an existing profile's title, hide title, list of disabled social platforms, or display the title.
Headers
Name
Type
Description
Authorization*
string
Format: Authorization: Bearer API_KEY. See Overview for more information.
Profile-Key*
string
Profile Key for a user profile.
Request Body
Name
Type
Description
disableSocial
array
Update the list of disabled profiles. The array will overwrite the previous list of disabled social networks.
Remove all disabled social by sending an empty array [].
Available networks:twitter, facebook, instagram, linkedin, telegram, gmb, youtube, tiktok, pinterest, and reddit.
Set to true or false to active messaging for this user profile. Messaging must be first be enabled for the account.
title
string
Updated title.
hideTitle
boolean
Update hide title.
displayTitle
string
Update display title.
tags
array
Tag user profiles using an array of strings. These tags serve as an internal organizational tool to categorize and manage your user profiles effectively.
Send an empty array [] to delete all tags.
<?php$url ='https://app.ayrshare.com/api/profiles';$apiKey ='API_KEY'; // Replace with your actual API key$profileKey ='PROFILE_KEY'; // Replace with your actual Profile key$data = ['title'=>'ACME Profile']; // Your data to be sent$curl =curl_init();curl_setopt_array($curl, [ CURLOPT_URL => $url, CURLOPT_RETURNTRANSFER =>true, CURLOPT_CUSTOMREQUEST =>'PATCH', CURLOPT_POSTFIELDS => json_encode($data), CURLOPT_HTTPHEADER => ['Content-Type: application/json','Authorization: Bearer '. $apiKey,'Profile-Key: '. $profileKey ],]);$response =curl_exec($curl);if (curl_errno($curl)) {echo'Error:'.curl_error($curl);} else {echojson_encode(json_decode($response), JSON_PRETTY_PRINT);}curl_close($curl);
Get all the profiles associated with the primary profile. The Primary Profile is not returned in the results.
For security, the Profile Keys are not returned via this GET call. Please see here for more information.
Query Parameters
Name
Type
Description
title
string
Return only the profile associated with the URL encoded title. Optional.
refId
string
Return only the profile associated with the given refId. The refId was returned during the profile creation or from the /user endpoint. Optional.
hasActiveSocialAccounts
boolean
If true return only profiles that have at least one connected social account (activeSocialAccounts length greater than zero). If false return only profiles with zero connected social accounts (activeSocialAccounts length is zero).
includesActiveSocialAccounts
array
Filter profiles to include those whose activeSocialAccounts contain all of the social media platforms specified in the includesActiveSocialAccounts list. Profiles can have additional platforms in their activeSocialAccounts beyond those listed in includesActiveSocialAccounts and still be included in the filtered results.
Values: facebook, instagram, linkedin, pinterest, gmb, reddit, youtube, tiktok, twitter.
Headers
Name
Type
Description
Authorization
string
Format: Authorization: Bearer API_KEY. See Overview for more information.
Unlink a social network for a given user profile. For example, if a user profile is linked to TikTok, unlink TikTok by making this endpoint request. A successful 200 response will be returned even if the platform is not linked. If the Profile-Key is not provided the Primary Profile's social account will be unlinked.
Headers
Name
Type
Description
Authorization*
string
Format: Authorization: Bearer API_KEY. See Overview for more information.
{"action":"post","status":"error","code":163, "message": "Missing, empty, or not valid platforms parameter. Please verify sending an array of valid platfoms. https://docs.ayrshare.com/rest-api/endpoints/post"
}
Generate a JSON Web Token (JWT) for use with single sign on. Used if you do not want to generate the JWT yourself. Also provided is the URL that can directly be used for SSO.
The JWT URL is valid for 5 minutes. After 5 minutes you must generate a new JWT URL. Please the Max Pack expireIn for additional options.
Headers
Name
Type
Description
Authorization*
string
Format: Authorization: Bearer API_KEY. See Overview for more information.
Request Body
Name
Type
Description
domain*
string
Domain of app. Please use the exact domain given during onboarding.
privateKey*
string
Private Key use for encryption.
profileKey*
string
User Profile Key. The API Key can not be used in this field.
logout
boolean
Automatically logout the current session. Recommend not to use in production since it affects the performance. Please see here.
redirect
string
Specify a URL to redirect to when the "Done" button or logo image is clicked. The URL will be automatically shortened in the returned JWT url. Redirect the origin opener window by adding the query parameter origin=true to the redirect URL.
verify
boolean
Verify that the generated token is valid. Recommend to only use in non-production environment. See below for details.
base64
boolean
If the private key is base64 encoded, set to true. Default false.
Encode the private.key file in base64 and pass the single line String in the privateKey field.
E.g in Linux: cat private.key | base64
expiresIn
number
Set the longevity of the token in minutes. Default 5 minutes. Range: 1 minute to 2880 minutes.
{"status": "success","title": "User Profile Title", "token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJhcGlLZXkiOiJBSjNQR1cxLThIWk04UjQtR0NXVFZKVy1ZRTE1M1BFIiwicHJvZmlsZUtleSI6IjhKNDY4UFktSjM5TVlXRC1IWEpLVlIyLVBRMjBQUlMiLCJpYXQiOjE2MTQyMjYwNDksImV4cCI6MTYxNDIyNjM0OSwiYXVkIjoiaHR0cHM6Ly9hcHAuYXlyc2hhcmUuY29tIiwiaXNzIjoiYm9uZGJyYW5kbG95YWx0eS5jb20iLCJzdWIiOiJzdXBwb3J0QGF5cnNoYXJlLmNvbSJ9.Se387OyhJIdaDkFkvAe0Dwo3pQrHBwdg2bbjqKYn7BZuVDxPboJmTsd7rra8N-Z6b9_fJOtwlRFGBLW1CvgLGU4RSisTVqjqhAkb3KNhpA7cZ673IJbRX-ST7tYadKKzmd9GNrZW9rhxHOlgMJ9uOboc4dcaDbNmzb_yCrfLY-E"
"url": "https://profile.ayrshare.com?domain=PROVIDED_DOMAIN&jwt=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJhcGlLZXkiOiJBSjNQR1cxLThIWk04UjQtR0NXVFZKVy1ZRTE1M1BFIiwicHJvZmlsZUtleSI6IjhKNDY4UFktSjM5TVlXRC1IWEpLVlIyLVBRMjBQUlMiLCJpYXQiOjE2MTQyMjYwNDksImV4cCI6MTYxNDIyNjM0OSwiYXVkIjoiaHR0cHM6Ly9hcHAuYXlyc2hhcmUuY29tIiwiaXNzIjoiYm9uZGJyYW5kbG95YWx0eS5jb20iLCJzdWIiOiJzdXBwb3J0QGF5cnNoYXJlLmNvbSJ9.Se387OyhJIdaDkFkvAe0Dwo3pQrHBwdg2bbjqKYn7BZuVDxPboJmTsd7rra8N-Z6b9_fJOtwlRFGBLW1CvgLGU4RSisTVqjqhAkb3KNhpA7cZ673IJbRX-ST7tYadKKzmd9GNrZW9rhxHOlgMJ9uOboc4dcaDbNmzb_yCrfLY-E",
"emailSent": true,// See details below"expiresIn": "30m"// See details below}
{"action": "JWT","status": "error","code": 189, "message": "Error generating JWT. Check the sent parameters, such as the privateKey has no extra tabs, spaces, or newlines. Error: error:0909006C:PEM routines:get_name:no start line"
}
constfs=require('fs');constAPI_KEY="API_KEY";constPROFILE_KEY="PROFILE_KEY";// Read in local private.key files - also can read from a DBconstprivateKey=fs.readFileSync('private.key','utf8');fetch("https://app.ayrshare.com/api/profiles/generateJWT", { method:"POST", headers: {"Content-Type":"application/json","Authorization":`Bearer ${API_KEY}` }, body:JSON.stringify({ domain:"ACME",// required privateKey,// required profileKey:PROFILE_KEY,// required }), }).then((res) =>res.json()).then((json) =>console.log(json)).catch(console.error);
import requests# Read in local private.key files - also can read from a DBwithopen('.private.key')as f: profileKey = f.read()payload ={'domain':'ACME','privateKey': profileKey,'profileKey':'PROFILE_KEY'}headers ={'Content-Type':'application/json','Authorization':'Bearer API_KEY'}r = requests.post('https://app.ayrshare.com/api/profiles/generateJWT', json=payload, headers=headers)print(r.json())
The Private Key must be precise, meaning preserving all characters including newlines. We recommend reading the private.key from a file to preserve all characters. If you paste the key into your code, you might need to manually replace newlines with a \n character or URL encode the string.
Pasting the key directly into code often gives issues.
It is recommend to first verify your data in Postman using generateJWT. You can then generate the code from Postman, or read the key file from a directory or database. Use the user's profile Profile Key in the profileKey field. Using the API Key in the profileKey field will result in an error.
❗Use the verify field in the /generateJWT endpoint to check the parameters.
Opening the JWT URL
Open the JWT URL in a new browser tab, browser window, or View Controller on iOS. The social networks do not allow opening the URL in an iFrame or obfuscating the approved partner origin domain.
1 minute video explaining how to generate a JSON Web Token (JWT):
Verify the JWT URL
The generateJWT endpoint does not validate the returned JWT URL by default. For example, if a corrupt Private Key is passed into generateJWT a URL will still be returned and the URL result in a 401 error.
You can verify the returned JWT URL by including verify: true in the generateJWT body parameters. If the JWT URL can not be validated an error will be returned. For example, if the Private Key had a character removed the following would be returned:
{"action":"JWT","status":"error","code":189, "message": "Error generating JWT. Check the sent parameters, such as the privateKey has no extra tabs, spaces, or newlines. Also the entire private.key file including -----BEGIN RSA PRIVATE KEY----- and -----END RSA PRIVATE KEY-----. Error: secretOrPrivateKey must be an asymmetric key when using RS256"
}
We recommend using verify: true only in a non-production environment since te validation takes additional processing time.
Bubble.io
If you are a Bubble user, please see Generate JWT Token in the Bubble.io section for instructions:
If you want a longer JWT timeout than the default 5 minutes, include the expireIn field.
For example, send the following JSON to set the JWT URL valid for 30 minutes:
{"expireIn":30}
This allows you to email the link to your users instead of them having to go to your app or platform. A common use case is if your user need to reconnect a social account, you can email them the JWT link to directly re-link the social account instead of having to navigate to your platform.
Be sure to review with your security team how long your business wants to keep the JWT alive. Longer expire times creates additional risk of an unauthorized party accessing the link.
Mobile JWT Examples
The following Swift, Flutter, and React Native code examples show how to launch the social linking page on an iOS device. Replace the jwtURL String variable with the return from the /generateJWT endpoint.
Swift (iOS)
In Swift, use a UIViewController and SFSafariViewControllerDelegate. We don't recommend using a WebView since some social networks such as Facebook and Google block authentication.
Flutter (Dart)
In Flutter (Dart), there is no direct equivalent to a UIViewController or the SFSafariViewController. However, you can achieve a similar functionality by using the url_launcher package to open web URLs.
React Native
React Native also doesn't have a direct equivalent to SFSafariViewController, but you can achieve a similar result with the WebBrowser API provided by expo-web-browser, which opens a URL in a modal browser window that shares cookies with the system browser. Otherwise, you can use the built-in React Native Linking function to open Safari: await Linking.canOpenURL(jwtURL);
/** * Using the API provided by expo-web-browser,* which opens a URL in a modal browser window that shares cookies* with the system browser. * Learn more about expo: https://reactnative.dev/docs/environment-setup?guide=quickstart** expo install expo-web-browser*/import React from'react';import { StyleSheet, Button, View } from'react-native';import*as WebBrowser from'expo-web-browser';exportdefaultfunctionApp() {constjwtURL='https://profile.ayrshare.com?domain=acme&jwt=eyJhbGciOiJ';constopenURLInBrowser=async () => {try {awaitWebBrowser.openBrowserAsync(jwtURL);// Optional: WebBrowser.openBrowserAsync returns a promise that resolves with an object containing// 'type' that can be 'cancelled' or 'dismissed'. You can use this to handle when the browser is closed. } catch (error) {console.error(error); } };return ( <Viewstyle={styles.container}> <Buttontitle="Open URL"onPress={openURLInBrowser} /> </View> );}conststyles=StyleSheet.create({ container: { flex:1, justifyContent:'center', alignItems:'center', },});
Connect Accounts Email
In conjunction with the longer expire time option, you can also automatically have Ayrshare email your users a link to the social linkage page.
Connect Accounts JSON
For example the following JSON will send an email to john@user.com with the company name ACME, contact email support@mycompany.com , and links to the terms and privacy policy:
The response will include the following if the email and expire time was set:
{
"emailSent": true,
"expiresIn": "30m"
}
Example JWT Connect Accounts Email
Here is an example of an email with the Connect Account link that opens social linkage page:
The email will come from the address: Social Connect Hub connect@socialconnecthub.com
Additional Information
Profile Key
All other endpoints, such as /user, /analytics, or /delete, can be called on behalf of a Profile account by adding the "Profile-Key" parameter in the Header.
For example, the /delete endpoint can be called to delete a Profile account's post for the given postid for the provided Profile Key.
Manage social account access for a User Profile when creating or updating.
It is important to note that disabled social networks in the global setting, set via the dashboard, override User Profile settings.
For example, if you turn disable TikTok access in the dashboard, then no User Profile can access TikTok. On the other hand, if you turn on TikTok access in the dashboard but disable it for a specific User Profile, all User Profiles will have access to TikTok except that particular one.
In addition to the /post endpoint spec, you can post to a User Profile by adding the Profile Key in the header. The return will be an array of posts or error results, with an overall status. If all posts successful, "success", or if any post failed, "error".
You may obtain a user's Profile Key via either the when the profile is created with the /create-profile endpoint or in Ayrshare's Web Dashboard GUI by switching to the profile and going to Profile Key page.
{
"status": "error",
"posts": [
{
"status": "error",
"errors": [
{
"action": "post",
"status": "error",
"code": 156,
"message": "Facebook does not seem to be linked with Ayrshare. Please confirm the linkage on the Social Accounts page in your dashboard. https://docs.ayrshare.com/additional-info/troubleshooting",
"platform": "facebook"
}
],
"postIds": [
{
"status": "success",
"id": "1381620363155607552",
"platform": "twitter"
}
],
"id": "2crtBXkWRsh9xbGThE1O",
"profileTitle": "Good Fun",
"refId": "da19d0d2875afb2a516cde881172eb6c1002c592",
"post": "What a wonderful post"
},
{
"status": "success",
"errors": [],
"postIds": [
{
"status": "success",
"id": "1381620363096899585",
"platform": "twitter"
},
{
"status": "success",
"id": "102775157855689_323026635830539",
"postUrl": "https://www.facebook.com/102775157858689_323026635030539",
"platform": "facebook"
}
],
"id": "7ojyAsPpLR0ZlyL6B5rz",
"profileTitle": "Digg It",
"refId": "866a36e1185b45e63f019386f941f320972b8e70",
"post": "What a wonderful post"
}
]
}
If a response of an array is required instead of an object, please include the body parameter arrayResponse with the boolean value of true. For example, arrayResponse: true
It is important to follow the rules of the social networks, especially in regards to duplicate or similar content. Please see here for details: