Generate a JWT

Generate a JSON Web Token (JWT) for use with single sign on.

Available on Business, Enterprise plans.

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. See the Max Pack expireIn for additional options.

Please see important information below for more details on this endpoint.

Header Parameters

Authorization

string

required

API Key of the Primary Profile.

Format: Authorization: Bearer API_KEY

Body Parameters

domain

string

required

Domain of app. Please use the exact domain given during onboarding.

privateKey

string

required

Private Key used for encryption.

profileKey

string

required

User Profile Key. The API Key cannot be used in this field.

logout

boolean

default: false

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

default: false

Verify that the generated token is valid. Recommend to only use in non-production environment. See below for details.

base64

boolean

default: false

If the private key is base64 encoded, set to true.

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

default: 5

Set the longevity of the token in minutes. Range: 1 minute to 2880 minutes.

Max Pack required. See below for details.

email

object

default: 5

Send a Connect Accounts email with a link for users to directly access their social linkage page. Max Pack required. See below for details.

Additional information

Switching Profiles

If you want to switch profile sessions, i.e. use a different profile, please see Automatic Logout of a Profile Session.

Private Key

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 recommended 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.

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

The social networks do not allow opening the URL in an iFrame or obfuscating the approved partner origin domain.

Generate a JSON Web Token

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 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.

Bubble.io

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

Bubble Generate JWT

JWT Expire In

Available on Business, Enterprise plans.Max Pack required

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

• Swift
• Flutter
• React Native

import UIKit
import SafariServices

class ViewController: UIViewController, SFSafariViewControllerDelegate {
    
    var jwtURL = "https://profile.ayrshare.com?domain=acme&jwt=eyJhbGciOiJ"

    override func viewDidLoad() {
        super.viewDidLoad()
        setupButton()
    }
    
    func setupButton() {
        let button = UIButton(type: .system)
        button.frame = CGRect(x: (view.bounds.width - 200) / 2, y: (view.bounds.height - 50) / 2, width: 200, height: 50)
        button.setTitle("Open URL", for: .normal)
        button.addTarget(self, action: #selector(buttonTapped), for: .touchUpInside)
        view.addSubview(button)
    }

    @objc func buttonTapped() {
        openURLInInAppBrowser()
    }

    func openURLInInAppBrowser() {
        if let url = URL(string: jwtURL) {
            let safariVC = SFSafariViewController(url: url)
            safariVC.delegate = self
            present(safariVC, animated: true, completion: nil)
        }
    }

    // Optional: If you want to handle when the in-app browser is closed
    func safariViewControllerDidFinish(_ controller: SFSafariViewController) {
        controller.dismiss(animated: true, completion: nil)
    }
}

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

{
  "email": {
    "to": "[e-mail]", // required
    "contactEmail": "[e-mail]", // required
    "company": "ACME", // required
    "termsUrl": "https://www.ayrshare.com/terms", // required
    "privacyUrl": "https://www.ayrshare.com/privacy", // required
    "expireIn": 60 // optional
  }
}

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 <[e-mail]>