Generate JWT Overview

The generateJWT endpoint generates a social network linking URL for a single User Profile. See the Business Plan API integration for more details.

​

Switching Profiles

To switch between different profile sessions (for example, when testing with multiple profiles), you’ll need to log out the current profile first. See Automatic Logout of a Profile Session for instructions on how to properly handle profile switching.

​

Private Key and Profile Key

​

Where to Get the Private Key

The Private Key file (private.key) and a sample Postman JSON file is inlcuded with your Integration Package recieved during onboarding. The Integration Package may also be retrieved in the Ayrshare developer dashboard in the API Page -> Integration Package.

​

Using the Private Key

We recommend reading the Private Key private.key from a file and sending it as a string in the privateKey field, which allows you to preserve all characters including newlines. The Private Key must be precise, meaning preserving all characters including newlines. 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 recommended to first verify your data in Postman using generateJWT. Included in the Integration Package is a sample Postman JSON file that you can use to verify your data.

You can also generate the code from Postman, or read the key file from a directory or database.

​

Include the Profile Key in the Header

Remember to use the user’s profile Profile Key in the Profile-Key header field along with the API Key.

​

Generate a JSON Web Token

1 minute video explaining how to generate a JSON Web Token (JWT):

The JWT URL is valid for 5 minutes. After 5 minutes you must generate a new JWT URL. See the [Max Pack expireIn]((/profiles/generate-jwt-overview#jwt-expire-in) for additional options.

​

Opening the JWT URL

Open the JWT URL in a new browser tab, browser window, or View Controller on iOS.

You may control the closing or redirecting of the new window or tab.

​

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 cannot 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 the validation takes additional processing time.

​

JWT Expire In

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.

​

Integrations

​

Bubble.io JWT

If you are a Bubble user, please see Generate JWT Token in the Bubble.io section for instructions:

​

Mobile JWT

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);

​

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 [email protected] with the company name ACME, contact email [email protected] , and links to the terms and privacy policy:

/**
  All fields are in the email object required.
  Missing fields will cause the email to fail.
*/
{
  "email": {
    "to": "[email protected]",
    "contactEmail": "[email protected]",
    "company": "ACME",
    "termsUrl": "https://www.ayrshare.com/terms",
    "privacyUrl": "https://www.ayrshare.com/privacy",
    "expireIn": 60
  }
}

The response will include the following if the email and expire time was set:

{
  "emailSent": true,
  "expiresIn": "30m"
}

​

JWT Connect Accounts Email Example

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 <[email protected]>