• API Home
• Custom Button Tutorial
• WaterWorld API Example

FreeCause Organization API

This document describes how clients and organizations can syndicate private buttons for a specific FreeCause Community Toolbar

Table of Contents

Introduction What is the FreeCause Organization API? What is a Custom Button? How it all Works Security Our Promise Password Security Request Format Domain Validation Toolbar time-based hash authentication string Implementation Getting Started Login/Logout Advanced Login API Core Deployment Managing your Custom Toolbar

API integrated features INCLUDE buttons Ticker Integrated Messaging Advanced Topics XSD validation Multiple INCLUDE Deployment Binary Variable Passing Advanced Security Topics

Introduction

What is the FreeCause Organization API?

The FreeCause Organization API allows clients to create toolbar
features that interface with secure, third-party web servers. It is
meant to allow end-users to log-in and access private user data through
the toolbar. Data could include private messages, user statistics,
friends, or high velocity data like threads on a private forum. All
client (toolbar) -> server (your organization's servers)
communication is done by bundling data in an XML transport layer.

What is a Custom Button?

A custom button is snippet of xml that when read by a FreeCause Toolbar
transforms into a normal toolbar button. Custom Buttons can be dynamic,
static, and can even call Javascript commands that interact with native
functions of the toolbar. Custom Buttons can be defined either
separately, or as a group, it all depends on how you want the buttons
to be displayed. Some organizations like to give their users a choice,
allowing them to pick and choose multiple private buttons, or simply
offering them a standard set. In the end, its all up to you! For a
more in depth look at custom buttons, please first read the Custom
Button Tutorial above or Click Here!

How it all Works

Step 1	User clicks a “login” button/link on the Toolbar.
Step 2	Toolbar loads a URL inside of a toolbar popup. The URL is an HTML web page that acts as the “login page”. It is hosted on your server and you can control the layout and design. The page must accept the user's information and validate it. This can either by done with a form submit or by using AJAX to validate the user credentials.
Step 3	After validation, the file returns a section of Javascript code to let the Toolbar know the session information (as described in password security)
Step 4	The toolbar then appends the returned session variables to all of its requests to any button urls that match the domain in the white-list

http://api.mysite.com/?rm=showCoolButton&user_id=gandhi34
			&session_key=some_hash&session_id=some_string&hash=some_hash

Step 5 The response xml is then turned into a custom button with private data!

Security

Our Promise

FreeCause can not, under any circumstance, recreate, steal, or monitor a users session with your servers. At FreeCause we understand the "holy" aspect of login credentials. Therefore, we take no part in the login process, using our simple API, login information never passes through our software.

Password Security

Users input their login credentials via a page that is hosted by your servers. Once their credentials are validated, the page outputs a simple javascript command, giving the toolbar three different values
• user_id: The identifying string or integer of your user, i.e. 'gandhi34'
• session_key:
  The session_key that validates subsequent requests. This session_key
  should be saved in a session table, this is a digest of sorts that
  should be used to keep track of users sessions. Also, this allows you
  to turn off a session if a request hasn't been made in a certain amount
  of time, or if you require them to log back in after being logged in
  for too long
• session_id: The session_id is a "safe
  string", it merely identifies the beginning of a new session and should
  be sent back to our servers from your servers. This is used by
  FreeCause to keep track of multiple users on the same toolbar, i.e. if
  a married couple uses the same computer to log in to different
  accounts. This way we can credit use for the toolbar to individual
  users, not just a computer

Request Format

All toolbar requests can be executed with SSL.

Domain Validation

The toolbars can send session information only to domains that are "white-listed" at compiling. Therefore, organizations must select at the beginning which domains/subdomains are allowed to receive session information. These settings files are all encrypted on the users computer, making it nearly impossible for third party software to patch.

Toolbar time-based hash authentication string

For all api components, the toolbar sends a set of authentication variables, along with a calculated md5 hash, comprised of the time, url, username, session_key, and your defined SECRET. This hash should ALWAYS be used for authenticating user information returned to the toolbar.

Example Url:
http://api.freecause.com/getgold.php?username=fr∓session_key=542346sd...
		
hash = md5 ( SECRETgetgold.php?username=fr∓session_key=542346sdfa2if0d2&time=111934303 );
		

This extra authentication allows you to be absolutetly sure that the request can not be easily duplicated. Your server side scripts should timeout these requests if the time sent differs by more than a couple seconds.

Implementation

Getting Started

The first thing you need to do is identify the following parameters.

• The domains that you want whitelisted (wildcards are accepted)
  
  

  api.mysite.com
  *.mysite2.com

• The url of your Login / Logout and Core API pages. (Core API page serves your custom features)
  

  <ORGANIZATION>
  	<SOURCE>http://api.mysite.com/core/</SOURCE>
  	<LOGIN>http://api.freecause.com/login/</LOGIN>
  
  	<LOGOUT>http://api.freecause.com/logout/</LOGOUT>
  </ORGANIZATION>

• What you want your custom toolbar to display. The SOURCE file location will be bundled with the toolbar and will allow you to syndicate multiple features within one file. You also have the choice of creating multiple toolbar INCLUDE components (explained later and in the Button Tutorial)

Login / Logout

Now that you've decided where the login and logout scripts go, use your server language of choice and create a simple form that will validate the username and password of your user. Once validated, either by AJAX or a form submit, the page must instantiate a toolbar Options object (a class that is defined within the toolbar), and send the required session information. The file below (sans actual validation), shows the simple JavaScript call that needs to be made.

<html>
<SCRIPT type="text/javascript">
var toolbar;

function ToolBarInit(tool){
      toolbar=tool;
}

function Authenticate(){
      toolbar.Options.Authenticated("some_user_id", "some_session_key", "some_session_id");
}
</SCRIPT>
<body>
<h1> LOGIN </h1>

<table border=0>
	<tr>
		<td>LOGIN:<td>
		<td><input id="username" type="text"/>
	</tr>
	<tr>
		<td>PASSWORD:<td>
		<td><input id="pwd" type="password"/><td>
	</tr>
	<tr>

		<td><button onclick="Authenticate();">Login</button><td>
</table>

</body>
</html>

This overly simplified example shows that once a user clicks on
Login, the Authenticated method of the Options object is called and
sets the user_id, session_key, and session_id for the toolbar session.
The Popup closes and the user is logged in!


Similarly, to login, the user will click on your predefined
link that logs them out of the toolbar. The toolbar simply redirects
the user to that link where the page has certain javascript calls that
clear the session variables from the toolbar, so that you can clear the
session. For example.

<html>
<SCRIPT>

var Options;

function OptionsInit(opts)
{
	Options = opts;
	Options.Authenticated("", "", "");
}

</SCRIPT>

<body>
<h1> logged out </h1>
</body>

</html>

Advanced Login (based on Flickr's Non-web based Authentication)

In order to have a more secure based authentication, we highly encourage developers to use this token based authentication.

• The Login url should contain an api_key that is set within the toolbar (for all toolbars):
  

  
  http://api.freecause.com/?api_key=g0d93964f9ddfb07aaad2d9012084e83
  			

• The login url then processes the api_key and generates an authentication token (or frob). The token is then in a hidden form and submitted with the form to the server. The frob allows your server to better authenticate that it is a toolbar user.
  

  <input type="hidden" name="api_key" value="g0d93964f9ddfb07aaad2d9012084e83" />
  <input type="hidden" name="frob" value="f490e23f6adae3719f9874c667f542d7" />
  			

• Once the form is submitted with the correct credentials, your server uses the frob,user,pass to generate the authenticating session_key in the same method as normal.
  

  <SCRIPT type="text/javascript">
  
  	var toolbar;
  
  	function ToolBarInit(tool){
  	      toolbar=tool;
  	}
  
  	function Authenticate(){
  	      toolbar.Options.Authenticated("some_user_id", "some_session_key", "some_session_id");
  	}
  </SCRIPT>
  			

  			<input type="hidden" name="api_key" value="f0d93964f9ddfb07aaad2d9012084e71" />
  			<input type="hidden" name="frob" value="f490e23f6adae3719f9874c667f542d7" />
  			

• Please reference Flickr for a more in depth look at token based authentication for non web-based applications: http://www.flickr.com/services/api/auth.spec.html

API Core

Now that you have a valid login and logout gateway, you can start building out your custom features. For this, you'll need some creativity and you should feel comfortable with the xml schema for custom buttons. If you need some further help, or more button examples, reference the Custom Button Tutorial above. For sake of simplicity we'll use php as the example server side script to output the buttons.

<?php
header('Content-type: text/xml');
?>
<xml xmlns="http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul">

<?
        #Retrive Variables
        $user_id = $HTTP_GET_VARS["user_id"];
        $skey = $HTTP_GET_VARS["session_key"];

        #Validate Username/Session Key - if not validated, show whatever you want.
        if($user == "" || $skey == "") {
?>
	<toolbaritem component="button">
		<toolbarbutton label="You have ? gold" />
	</toolbaritem>
	<toolbaritem component="button">
		<toolbarbutton label="Login"
		  oncommand="FC_Toolbar.LoadURL('{$login}?toolid=%toolid&userid=%userid&key=%userkey', 'apipopup', 'height=200,width=400')"/>

	</toolbaritem>

<?
        }
		#Print out user specific buttons/information if Validated
        else {
?>
	<toolbaritem component="button">
		<toolbarbutton label="Welcome <?echo $user_id?>"/>
	</toolbaritem>

	<toolbaritem component="button">
		<toolbarbutton label="You have 35 gold" />
	</toolbaritem>
	<toolbaritem component="button">
		<toolbarbutton label="Logout" oncommand="FC_Toolbar.LoadURL('{$logout}?%api_auth', 'apipopup', 'height=200,width=300')"/>
	</toolbaritem>

<? } ?>

Going through the file, if I hit http://api.mysite.com/core/ with no credentials (loading the browser), my toolbar will show me two buttons, one that says "I have ? gold" and the other a Login button. Once I click login, an 'apipopup' (a toolbar popup) will load and I can enter in my user/pass credentials. Once I sign in, the API sends all of the session information returned from the Options.Authenticated method back to Core.php, and it will Welcome me and display private date from the site. The point to understand from this example is that your Core.php file can return any of the advanced buttons explained in the Button Tutorial.

Deployment

Now lets integrate all of these components and show them in the toolbar. If you have already received your binary and xpi from FreeCause, great! If you haven't, you'll need to contact us to add the domain/script parameters to the toolbar binaries so your users informations stays secure. Most likely FreeCause will have made all the required changes for you, however, if we haven't, contact us and we can help you immediately! Once you have the binaries, install, log in, and check out your custom toolbar.

Managing your Custom Toolbar

Managing your Custom Toolbar couldn't be easier. Launching in early October 2007, FreeCause will integrate the custom api features completely with the Administration Center.


Tools that will be added

• Add/Modify/Delete custom components across toolbar environment
• Integrated custom component statistics
• Custom component AJAX test bed
• Private data feeds for the Messaging Component
• Advanced Security Features and Notifications

API integrated features

INCLUDE buttons

Include buttons are the heart and soul of the organization API. INCLUDE buttons can return one button, or multiple buttons. This freedom allows you to offer your end users as many different private features as you want. Deploying multiple includes for organization is explained in a later section. For now, lets evaluate the API Core file as an include button to get started.

Ticker

Our ticker accepts xml in a standard RSS 2.0 format. Using %api_auth, you can have the ticker display any type of private message feeds through the ticker.

Integrated Messaging

Using the existing messaging feature available on the toolbar, clients can integrate private messages, private forums, or any other private data very easily. The messaging component accepts a standard RSS 2.0 format.

<?xml version="1.0" encoding="UTF-8"?>

<rss version="2.0">
	<channel>
	<title>My Site</title>
	<link></link>
	<description></description>

	<language>en-us</language>
	<copyright></copyright>
	<lastBuildDate></lastBuildDate>
		<item>
			<title><![CDATA[[Thomas344 wants to be your friend]]]><</title>

			<link></link>
			<description><![CDATA[[Thomas344 wants to be your friend, go to your friends secion to add him]]]></description>
			<author></author>
			<guid isPermaLink="false"></guid>

			<pubDate>09-01-2007</pubDate>
		</item>
	</channel>
</rss>

To add a private data feed to the messaging component you will need to add a custom data feed in the Administration Center (Available early October 2007). Until October, please interface with FreeCause and we will be able to add the data feeds very quickly. The data feeds should be in the form of an INCLUDE button, using %api_auth

Advanced Topics

XSD Validation

Our XML Schema

Multiple INCLUDE Deployment

Deploying with multiple includes is a great way for you to give your end users more than just one set of tools to interact with your online community, marketplace, or world. The simplest way is that you can use our javascript interface and host a small button gallery on one of your white-listed domains. Below shows a simple example:

<HTML>
<BODY>
<script>
var toolbar;
function ToolBarInit(tool)
{
	toolbar = tool;
}
function AddTest()
{
	toolbar.addComponent(
	'<xml xmlns="http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul">'+
	'	<toolbaritem component="include" url="http://api.mysite.com/gcounter?%api_auth"/>'+
	'</xml>');
	toolbar.Reload();
	return false;
}
</script>

<A href="#" onclick="return AddTest();">Add Test Component for OrgAPI

</BODY>
</HTML>
		

This page, on a white listed domain, will add the button described by the INCLUDE component into the users toolbar. %api_auth appends all the required authorization variables to the url, and the toolbar.Reload() function reloads the toolbar to see the new addition.

Binary Variable Passing

For deep integration with an existing database of end-user information, clients can send email blasts with binary variables attached. This allows clients to integrate their backend data with our statistics and messaging features. The variables will be patched into the install file and returned to FreeCause servers when the toolbar instantiates.

http://mysite.freecause.com/install.exe?email=test@mysite.com&var2=value2

FreeCause's database stores:



email -> test@mysite.com

var2 -> value2

Note: Since the user and others can see (and modify) variables and
values, you should not use this to pass to any sensitive information.

<!--

Statistics Gathering

-->

Advanced Security Topics

For clients that want to incentivize with virtual goods based on toolbar
usage, some advanced security measures are available. We can offer mac address user binding, ip limit notification, location based normal usage regression tests, just to name a few. Since these services are not currently integrated you will need to contact your FreeCause representative about integration.