The Ambassador Developer Hub

Welcome to the Ambassador developer hub. You'll find comprehensive guides and documentation to help you start working with Ambassador as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    

Single Sign-on

Single Sign-on

To enable a user to seamlessly login to both your website and their ambassador portal, please complete the following steps:

  1. Ensure you have access to single sign-on with your plan. If you're not sure, please check with your success coach.
  2. Copy the code snippet below and modify for your language/framework of choice to generate your SSO login URL.
  3. Trigger the code on the page that follows a successful authentication (user login) on your website.
  4. Populate the $mbsy_email variable in the snippet. You can use all other parameters listed in the ambassador/get API method.
  5. Ensure you call the company/token API method to get a new token before generating each SSO login URL. The token is short-lived and only good for one use.
  6. Authenticate your user via SSO using one of the following two methods:
    • Display an tag with the src attribute set to your SSO login URL (example below) after your user has logged in to your site. Then redirect your user to https://[[app:username]] when they perform some action such as clicking a button to access your referral program.
      <img src="<?php echo $sso_login_url; ?>" style="border: none; visibility: hidden" alt="" />
    • Redirect your user to your SSO login URL with the additional parameter "return_url=https://[[app:username]]". You would typically do this using a link/button your user clicks to access your referral program.

NOTE: To logout a user, do the same and change 'login' to 'logout' in your SSO login URL. Your SSO login URL with its required parameters is https://[[app:username]]

Custom Portal Domain

If you are using a custom portal domain, then you should use your custom domain in the SSO URL instead of the default URL which is shown in the example.


    $username = '[[app:username]]';
    $api_key = '[[app:key]]';
    $response_type = 'json';
    $mbsy_token = '';
    $mbsy_email = ''; // Set this to the value of your user's email
    $mbsy_signature = sha1($api_key.$mbsy_email);

    // Build and make company/token API call
    $url = ''.$username.'/'.$api_key.'/'.$response_type.'/company/token';
    $curl_handle = curl_init();
    curl_setopt($curl_handle, CURLOPT_URL, $url);
    curl_setopt($curl_handle, CURLOPT_CONNECTTIMEOUT, 10);
    curl_setopt($curl_handle, CURLOPT_RETURNTRANSFER, TRUE);
    curl_setopt($curl_handle, CURLOPT_FOLLOWLOCATION, TRUE);
    curl_setopt($curl_handle, CURLOPT_POST, FALSE);
    curl_setopt($curl_handle, CURLOPT_FAILONERROR, FALSE);
    curl_setopt($curl_handle, CURLOPT_SSL_VERIFYPEER, FALSE);
    curl_setopt($curl_handle, CURLOPT_SSL_VERIFYHOST, FALSE);
    $response = curl_exec($curl_handle);

    // Decode json response to array, you'll need to change this if using XML
    $response = json_decode($response, TRUE);

    // Grab token from response
    $mbsy_token = $response['response']['data']['token'];

    // SSO login URL
    $sso_login_url = 'https://[[app:username]]' . $mbsy_token . '&email=' . urlencode($mbsy_email) . '&signature=' . $mbsy_signature;