The OpenWeb Developer Hub

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

Get Started    Documentation

Implement single sign on

OpenWeb’s single sign-on (SSO) process allows using your existing identity management solutions with OW products.

Requirements

You must request the following from your OpenWeb PSMPSM - Partner Success Manager:

  • OpenWeb SSO enabled for your site
  • Your secret access token

📘

TIP

If you do not currently have any user management solution implemented on your site, OpenWeb can also be used as your primary user management solution.

You can also enable single sign on through one of our third-party SSO partners.



SSO Handshake Overview

The following steps and diagram provide an overview of how an SSO handshake is initiated and completed:

  1. Listen for the spot-im-api-ready event. (You can also listen for other OpenWeb events.)
  2. Initiate an OpenWeb SSO session. OpenWeb generates an SSO session ID (codeA).
  3. Send the SSO session ID to your backend user management system.
  4. Validate that a user is logged into your system. You must ensure that the current user logged into your site will also be the current user in the OpenWeb user session.
  5. From your backend user management system, make a GET /sso/v1/register-user call to OpenWeb. The API call must include the following information:

    • Your secret access token (access_token)
    • Session ID generated after initiating the SSO session (code_a)
    • Required user details from your backend user management system (primary_key, user_name).

    OpenWeb logs in the user and returns a success response (codeB).
  6. Pass codeB to OpenWeb. Successfully completing this process results in logging in a user.
Single sign on sequence diagramSingle sign on sequence diagram

Single sign on sequence diagram


Sample Implementation

You have the flexibility to implement the login process in a way that aligns with the design of your site. The following frontend and backend code samples show one approach to implement single sign on.


Frontend Login

Use the following example and table to add the frontend login code to your page.

This code example listens for spot-im-api-ready. Depending on the user experience you want to create, you can also listen for other frontend events to initiate the SSO handshake process.

When the SSO API is ready, the SSO process is initiated by window.SPOTIM.startSSO(callback,userId).


if (window.SPOTIM && window.SPOTIM.startSSO) {
    startSSO();
} else {
    document.addEventListener('spot-im-api-ready', startSSO, false);
}

// Prior to initiating this function, ensure that the user
// is actively logged into your site
function startSSO() {
    var callback = function(codeA, completeSSOCallback) {
        // call your backend to receive codeB and return it
        // to OpenWeb via completeSSOCallback function
        fetch('YOUR_BACKEND_URL', {
            method: 'POST',
            body: {
                code_a: codeA,
            }
        }).then(res => res.json()).then(codeB => {
            if(codeB){
                completeSSOCallback(codeB)
            }
        });
    };
    window.SPOTIM.startSSO({callback: callback, userId: <unique-user-id>}).then(function(userData) {
        // userData contains information about the logged in user
    })
    .catch(function(reason) {
        // reason contains error details
    });
}

window.SPOTIM.startSSO ({callback: callback, userId: <unique-user-id>})

ArgumentDescription
callback* functionFunction that initiates and completes the login handshake

The codeA argument calls your backend endpoint. The backend endpoint asks to register a user with or log in a user to OpenWeb and receives codeB to confirm the success of the process.

The completeSSOCallback argument accepts codeB to complete the login handshake.
userId* stringEnables OpenWeb to handle the login and logout logic

OpenWeb compares the userId passed into the method with the userId that exists in local storage when window.SPOTIM.startSSO() is executed. This is one approach to ensure that the OpenWeb session is always synced.

If the userId matches, no additional steps are required. The user is the same.

If the userId does not match, OpenWeb performs the following actions:
• Run window.SPOTIM.logout() to log out the existing user.
• Log in the new user.
• Replace the current userId attribute in local storage.

Backend SSO Handshake

Your backend user management system must log in the current user into OpenWeb and communicate the result back to the frontend code above.

From your backend user management system, make a GET /sso/v1/register-user call to OpenWeb. The API call must include your secret access token (access_token), the session ID generated after initiating the SSO session (code_a), and required user details from your backend user management system (primary_key, user_name).

📘

NOTE

Each of these parameters is defined in the Add user information section.

Also by making a modified GET /sso/v1/register-user call, you can configure email notifications that OpenWeb sends to your users on your behalf and add a user bio.

GET https://www.spot.im/api/sso/v1/register-user?code_a={CODE_A}&access_token={ACCESS_TOKEN}&primary_key={PRIMARY_KEY}&user_name={USER_NAME}

The API returns code_b as raw text.

vzFQZwLz670glmBv9lIV0%

Add user information

In addition to the required parameters, additional user information that you can append to the GET /sso/v1/register-user call are listed in the following table.

ParameterDescription
access_token*Secret access token provide by OpenWeb
code_a*Session ID returned after initiating an SSO session
primary_key*Unique user ID generated by a Partner’s backend user management system
user_name*Unique username generated by a Partner’s backend user management system

Once OpenWeb validates the uniqueness of the username, the username is registered to the user.
display_nameFull name of the user
emailEmail of the user
email_verifiedIndicates that the email of the user has been verified

Possible values:
   • true
   • false

Falsely indicating that an email address has been verified violates OpenWeb’s terms of use. Once identified, OpenWeb will invalidate all users.
image_urlURL of the profile image of the user

This image is the avatar used for all comments created by the user. If the image_url is not set, OpenWeb selects a random avatar from the avatar scheme for the user.
locationLocation of the user
private_profileIndicates that the user's commenting history cannot be viewed by others

Possible values:
   • false (default)
   • true
user_metadataIndicates if the user is a subscriber or not and enables the segmentation of data by subscribers and non-subscribers

If a user's subscriber status changes, you must log out the user and complete a new SSO flow. This ensures that a user's previous cached client state for user_metadata.is_subscriber is not used.

Possible values (values must be Base64-encoded):

{
  "is_subscriber": true
}

When this value is passed for a user, you can also show a customized subscriber badge next to the user's name in the Conversation. Please contact Support to enable and customize the subscriber badge.



{
  "is_subscriber": false
}


Configure additional user settings

You can also use GET /sso/v1/register-user to configure a user's email notification settings or add a bio.

  1. Configure the following JSON object.
{
    "bio": "This is my personal bio",
    "settings": {
        "notifications": {
            "email": {
                "liked_your_message": "immediately|never",
                "message_approved": "immediately|never",
                "message_rejected": "immediately|never",
                "replied_to_message": "immediately|never",
                "user_mentioned": "immediately|never"
            }
        }
    }
}
PropertyDescription
bio stringUser bio

When configuring a user bio, the bio cannot exceed 200 characters. This property can be passed with or without the settings object.
settings objectEmail notification settings

When configuring email notifications, be sure to choose either "immediately" or "never" as the value for each settings.notifications.email property. This property can be passed with or without the bio property.

  1. Add the Content-Type: application/json header to the GET /sso/v1/register-user call and append the JSON object from the previous step.
curl -X GET https://www.spot.im/api/sso/v1/register-user?code_a={CODE_A}&access_token={ACCESS_TOKEN}&primary_key={PRIMARY_KEY}&user_name={USER_NAME}
 -H 'Content-Type: application/json' \
 -d '{"bio":"This is my personal bio","settings":{"notifications":{"email":{"liked_your_message":"immediately|never","message_approved":"immediately|never","message_rejected":"immediately|never","replied_to_message":"immediately|never","user_mentioned":"immediately|never"}}}}'


Trigger your log-in screen

Certain OpenWeb features can require users to be logged in. These includes writing comments, voting on other comments and more. When such policy is active in SSO, you receive an event notification to initialize your login process:

document.addEventListener('spot-im-login-start', function(event) {
    // trigger your login flow here
});


Log out a user

When a registered user logs out from your system, the same user must be logged out from OpenWeb. Use window.SPOTIM.logout() to end a registered user’s OpenWeb session.



if (window.SPOTIM && window.SPOTIM.logout) {
    window.SPOTIM.logout();
} else {
    document.addEventListener('spot-im-api-ready', function() {
        window.SPOTIM.logout();
    }, false);
}


Manage users

Through backend API calls, OpenWeb enables you to manage your registered users:


Making calls from the Partner backend to the OpenWeb backend ensures that the access token in the HTTP request header is not compromised. Use the secret access token provided to you by OpenWeb.


Register a new user


Register a new SSO user to OpenWeb

POST https://www.spot.im/api/sso/v1/user
Header: x-spotim-sso-access-token: ACCESS_TOKEN

Query Parameters

ParameterDescription
spot_id*Your OpenWeb account identifier
primary_key*Unique user ID generated by a Partner’s backend user management system
user_name*Unique username generated by a Partner’s backend user management system

Once OpenWeb validates the uniqueness of the username, the username is registered to the user.
display_nameFull name of the user
emailEmail of the user
email_verifiedIndicates that the email of the user has been verified

Possible values:
   • true
   • false

Falsely indicating that an email address has been verified violates OpenWeb’s terms of use. Once identified, OpenWeb will invalidate all users.
image_urlURL of the profile image of the user

This image is the avatar used for all comments created by the user. If the image_url is not set, OpenWeb selects a random avatar from the avatar scheme for the user.
locationLocation of the user
private_profileIndicates that the user's commenting history cannot be viewed by others

Possible values:
   • false (default)
   • true
user_metadataIndicates if the user is a subscriber or not and enables the segmentation of data by subscribers and non-subscribers

If a user's subscriber status changes, you must log out the user and complete a new SSO flow. This ensures that a user's previous cached client state for user_metadata.is_subscriber is not used.

Possible values (values must be Base64-encoded):

{
  "is_subscriber": true
}

When this value is passed for a user, you can also show a customized subscriber badge next to the user's name in the Conversation. Please contact Support to enable and customize the subscriber badge.



{
  "is_subscriber": false
}

Retrieve user details


Retrieve the OpenWeb user data of an existing SSO user

GET https://www.spot.im/api/sso/v1/user/primary_key
Header: x-spotim-sso-access-token: ACCESS_TOKEN

Path parameter

ParameterDescription
primary_key*Unique user ID generated by a Partner's backend user management system

Update user details


Update the OpenWeb user data of an existing SSO user

In order to simplify the process, OpenWeb expects the full data of the user.

GET https://www.spot.im/api/sso/v1/update-user
Header: x-spotim-sso-access-token: ACCESS_TOKEN

Query Parameters

ParameterDescription
primary_key*Unique user ID generated by a Partner’s backend user management system
user_name*Unique username generated by a Partner’s backend user management system

Once OpenWeb validates the uniqueness of the username, the username is registered to the user.
display_nameFull name of the user
emailEmail of the user
email_verifiedIndicates that the email of the user has been verified

Possible values:
   • true
   • false

Falsely indicating that an email address has been verified violates OpenWeb’s terms of use. Once identified, OpenWeb will invalidate all users.
image_urlURL of the profile image of the user

This image is the avatar used for all comments created by the user. If the image_url is not set, OpenWeb selects a random avatar from the avatar scheme for the user.
locationLocation of the user
private_profileIndicates that the user's commenting history cannot be viewed by others

Possible values:
   • false (default)
   • true
user_metadataIndicates if the user is a subscriber or not and enables the segmentation of data by subscribers and non-subscribers

If a user's subscriber status changes, you must log out the user and complete a new SSO flow. This ensures that a user's previous cached client state for user_metadata.is_subscriber is not used.

Possible values (values must be Base64-encoded):

{
  "is_subscriber": true
}

When this value is passed for a user, you can also show a customized subscriber badge next to the user's name in the Conversation. Please contact Support to enable and customize the subscriber badge.



{
  "is_subscriber": false
}

Body Parameters

You can also use GET /sso/v1/update-user to configure a user's email notification settings or add a bio.

  1. Configure the following JSON object.
{
    "bio": "This is my personal bio",
    "settings": {
        "notifications": {
            "email": {
                "liked_your_message": "immediately|never",
                "message_approved": "immediately|never",
                "message_rejected": "immediately|never",
                "replied_to_message": "immediately|never",
                "user_mentioned": "immediately|never"
            }
        }
    }
}
PropertyDescription
bio stringUser bio

When configuring a user bio, the bio cannot exceed 200 characters. This property can be passed with or without the settings object.
settings objectEmail notification settings

When configuring email notifications, be sure to choose either "immediately" or "never" as the value for each settings.notifications.email property. This property can be passed with or without the bio property.

  1. Add the Content-Type: application/json header to the GET /sso/v1/update-user call and append the JSON object from the previous step.
curl -X GET https://www.spot.im/api/sso/v1/update-user?primary_key={PRIMARY_KEY}&user_name={USER_NAME}
 -H 'Content-Type: application/json' \
 -H 'x-spotim-sso-access-token: {ACCESS_TOKEN}' \
 -d '{"bio":"This is my personal bio","settings":{"notifications":{"email":{"liked_your_message":"immediately|never","message_approved":"immediately|never","message_rejected":"immediately|never","replied_to_message":"immediately|never","user_mentioned":"immediately|never"}}}}'

Delete user details


Delete the OpenWeb user data of an existing SSO user

When requested by a user, you must delete the user’s OpenWeb account to remain GDPR compliant. Once the user has been deleted, comments by the deleted user remain and are linked to a random guest user.

DELETE https://www.spot.im/api/sso/v1/user/primary_key
Header: x-spotim-sso-access-token: ACCESS_TOKEN

Path parameter

ParameterDescription
primary_key* stringUnique user ID generated by a Partner's backend user management system

Updated 25 days ago


Implement single sign on


OpenWeb’s single sign-on (SSO) process allows using your existing identity management solutions with OW products.

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.