Authentication mechanism

The authentication is based on Facebook authentication (token and signed request).
All requests done to the API must contains authentication parameters otherwise they will receive a 401 Unauthorized answer.

The <project-tag> URL parameter is essential in all the calls, and a verification will be done between the parameters, user and project tag.

Authentication request information

Authentication URL request parameters

Parameter	Mandatory	Description
project-tag	X	The project identifier (name and year of the project). Format: name-YYYY
UPID		The user's project ID (UPID). Only needed when accessing request related to a user.

Authentication POST request parameters

Parameter	Mandatory	Description
auth_type	X	Facebook Web: "facebook" Facebook Mobile call: "facebook-mobile" Showclix: "showclix"
auth_token	X	Web call: The Facebook signed request from the authentication. See Facebook authentication sample code below. asdf Mobile call: A base64 encoded JSON whose structure should be: { "user_id": <facebook user id>, "access_token ":<access_token>, "app_id ": <app_id> } Showclix: The validation token provided by the Showclix API
auth_user_id		Required for the Showclix authentication, the user ID is provided by the Showclix API

Authentication response information

Response code

401 Unauthorized: The combination of the authentication parameters (project tag, UPID, auth type, auth token) is incorrect.
- Possible issues:
  - Project tag is incorrect
  - UPID you are using is related to the FB token you are sending
  - Facebook app ID used is not the one stored on Greencopper side, and the verification with Facebook app secret failed.
    Greencopper is the only owner of the Facebook App Secret. If the app is shared with you for other reason, please ensure you never reset the Facebook App Secret and never share it.
  - Authentication token is expired. You can store it and use it after it have expire. Please check https://developers.facebook.com/docs/reference/login/signed-request/ for more information.

Web sample - JavaScript implementation

Sample code based on jQuery and the Facebook JavaScript SDK.
See the /user method to get more information about user login.

/*
 * Sample code to 
 */
callFavsSyncEndpoint: function(){
 
    // Ensure there is a signed request for the current user
    var signedRequest = this.getFacebookSignedRequest();
    if (signedRequest == null) {
        // Can not call API without a valid Facebook signed request
        return;
    }
    // Call the API
    jQuery.ajax({
        type: 'POST',
        url: '<API_endpoint>',
        data: { auth_type: "facebook", auth_token: signedRequest, <other_parameters_if_needed> },
        success: function( data ) {
            // Request success
        },
        error: function(jqXHR, textStatus, errorThrown) {
			// Request failed, check response code
        }
    });
},

/**
 * Returns the current Facebook signed request or null if none.
 */
getFacebookSignedRequest: function() {
    var authResponse = (typeof FB === 'object') ? FB.getAuthResponse() : null;
    if (authResponse != null && typeof authResponse.signedRequest !== 'undefined') {
        return authResponse.signedRequest;
    }
    return null;
},