Forums

Handles authentication for third-party forum integrations. If the customer is logged in, these endpoints return data about the user, which is subsequently used by the forum. The data both passed in and returned is signed with a signature, which is computed with a shared secret, to verify that the request and response were generated by systems under our control.

The login endpoints are expected to be called from a library or script during the single sign-on process for one of these hosted forums:

• IP.Board (ssoPublicSessions.php)

GET /forums/:fanclub_id/ipboard_login

Authenticate via ssoPublicSessions.php for IP.Board forums.

Request

Responses

Success: Logged in customer

{
    "id": "1",
    "name": "sparkslice1",
    "email": "naveen@sparkart.com",
    "joined": "1340064000",
    "member_group_id": 32,
    "rand": 0.3635491426659091,
    "signature": "c8edd52a178c7c95a07e14f3d352b6ae594f0662"
}

Notes:

• signature is an sha1 hash of the sorted parameters other than signature itself and including the IP.Board secret (the License Key). In this example, if the shared secret is secret123, the signature is calculated as sha1("email=naveen%40sparkart.com&id=1&joined=1340064000&member_group_id=32&name=sparkslice1&rand=0.3635491426659091secret123")
• rand is added to the response to increase the entropy of the signature. It is not used by IP.Board other than to verify the signature.

Failure: No current customer

{
    "error": "access_denied",
    "message": "Not logged in."
}

Failure: Timestamp missing

{
    "error": "invalid_request",
    "message": "The timestamp is missing or invalid."
}

Failure: Timestamp invalid (off by more than 30 minutes from current time)

{
    "error": "invalid_request",
    "message": "The timestamp is invalid."
}

Failure: Signature missing

{
    "error": "invalid_request",
    "message": "The signature is missing."
}

Failure: Signature invalid

{
    "error": "access_denied",
    "message": "Signature invalid."
}

GET /forums/logout.js

Returns a Javascript file to be included in the forum template. The script will bind to the "sign out" or "log out" button in the forum, triggering a logout request to the API so that the customer will be logged out of both the forum and the fanclub.

Request

No parameters required (besides your API key of course).

Typical use case is including this script via the <script> tag in the forum template HTML:

<script src="https://services.sparkart.net/api/v1/forums/logout.js?key={key}"></script>

Responses

Success (with example API key: abfa2835-4c12-46cc-aa5d-8f259213b8e1)

if (typeof jQuery === "undefined") {
    loadjQuery("//ajax.googleapis.com/ajax/libs/jquery/1.11.0/jquery.min.js", bindLogout);
} else {
    bindLogout();
}

function loadjQuery(url, callback) {
    var script_tag = document.createElement('script');
    script_tag.setAttribute("src", url)
    script_tag.onload = callback; // Run callback once jQuery has loaded
    script_tag.onreadystatechange = function() { // Same thing but for IE
        if (this.readyState == 'complete' || this.readyState == 'loaded') callback();
    }
    document.getElementsByTagName("head")[0].appendChild(script_tag);
}

function bindLogout() {
    jQuery.noConflict();

    jQuery(document).ready(function() {
        jQuery("a[href*=logout], a[href*=signout]").click(function( event ){
            event.preventDefault();

            var forumLogout = jQuery(this).attr("href");
            var universeLogout = {
                type: "GET",
                dataType: "json",
                url: "https://services.sparkart.net/api/v1/logout.json?key=abfa2835-4c12-46cc-aa5d-8f259213b8e1"
            };

            // Use JSONP if this is IE 9 or earlier
            if( jQuery.support.cors ){
                universeLogout.crossDomain = true;
                universeLogout.xhrFields = { withCredentials: true }
            } else {
                universeLogout.dataType = "jsonp";
                universeLogout.data = { "_method": "GET" }
            }

            jQuery.ajax(universeLogout).done(function(){
                window.location = forumLogout;
            });
        });
    });
}

Failure: Missing or invalid fanclub API key

{
    "status": "error",
    "messages": [
       "Please use a valid API Key."
    ]
}