If your site has its own login system and database with user information you can use this API to sync it with the SuperSaaS user database. This allows you to provide your users with a way to register and log in only once.
There are several options to keep the SuperSaaS database updated using the API calls below. The simplest implementation consists of a single button:
This way of working allows you to only sync the subset of your users who are actively using SuperSaaS and avoids the need for an initial full sync. In theory, there's a small risk of the databases getting out of sync if you only implement the button. This can happen if the user's information is changed on your site and he then returns to SuperSaaS without clicking the button, for example because he has bookmarked the page. If this is an issue you could implement the server side API calls detailed below to send the updated information from your server directly to SuperSaaS each time user information changes on your site. The API calls have options to make them silently fail on non-existing users so you can still keep only the subset of active users in SuperSaaS.
An alternative to the procedure above is to do an initial sync of your entire user database (manually or automated), and on each update to your own database send an API call from your server to keep SuperSaaS in sync. You can then create a simple link to log them in automatically and redirect them to your schedule.
You could also make your own database follow the changes in SuperSaaS but in the following discussion we assume that you want to make your own database leading and let SuperSaaS follow that. Therefore you want to prevent people from changing their information in the SuperSaaS database. You will want to make the following settings:
The easiest way to implement single sign-on is to provide all the needed information when you send the user over from your site. SuperSaaS will check if the user already exists and update or create the database record as appropriate.
This is an illustrative HTML snippet that you would put on your site to make this work:<form method="post" action="http://www.supersaas.com/api/users"> <input type="hidden" name="account" value="Your_account_name"/> <input type="hidden" name="id" value="1234fk"/> <!-- A unique key to identify the user. See below --> <input type="hidden" name="user[name]" value="joe@client.com"/> <!-- Any string. Needs to be unique --> <input type="hidden" name="user[phone]" value="123-456-789"/> <!-- values for other fields, see the bottom of the page for a list --> <!-- you can add and remove fields in the "Access Control" screen --> ... <input type="hidden" name="checksum" value="A4E67...DFEF"/> <!-- 32 digit MD5 Hash, see below --> <input type="hidden" name="after" value="schedule_name"/> <!-- where you send your user after sign on --> <input type="submit" value="Book now"/> </form>
To see this snippet filled in with appropriate values for your account see this example. If you happen to use Joomla, Drupal or Wordpress as a content management system then you can download a ready-made Joomla module, Drupal module or WordPress plugin.
To be able to keep track of changes both databases need to use the same unique key. This ID needs to be sent along with each transaction to identify the record that needs to be modified. To facilitate easy implementation you have three options to choose from:
The API supports several different types of authentication. For server to server communication you can send your account name and password as URL parameters, or in an HTTP basic authentication header, and optionally protect the connection with SSL. However you cannot, of course, put your account password in the HTML code such as the snippet above, because that would reveal your password to anyone who looked at the source of the page. To authenticate an HTML request without sending a password you can calculate a one-way MD5 hash of several fields and add that to the request. The hash is calculated from a concatenated string that includes your account name, the user name and your account password (not the user's password). Since it includes the account password which is only known to you and SuperSaaS, it cannot be calculated by anyone else. Because the checksum includes the visitor's name it is different for every visitor and you can safely put it in an AJAX call to be performed by the browser. Most languages provide an easy way to calculate an MD5 hash, for example:
$user = 'user_name@client.com';$checksum = md5("Your_account_nameYour_account_password$user")checksum = Digest::MD5.hexdigest("Your_account_nameYour_account_password#{'user_name@client.com'}")
Note that there is no need to provide the user's password since the form is already authenticated with the checksum. You can send a user password but it is better not to do so since it would be visible in the source of the web page. If the record was successfully created or updated the user is redirected to the URL contained in the "after" parameter. You can provide additional values in this URL to ensure the user ends up at pre-determined date and view. It can also contain pre-fill values for the booking fields as explained in the integration tutorial.
If you only provide the sign-on button and stop there then the two databases can get out of sync, which you may, or may not, find acceptable. For instance, a person can change his information on your site and then make his way back to SuperSaaS without going through the link, perhaps because he uses his browser history. Also, a user that you delete from your own database will not be removed from the SuperSaaS database. To avoid this you can update the SuperSaaS database from your own server by sending the API calls detailed below each time user information changes on your server.
If you have already managed to get the databases in sync, either manually or with the API calls below, you can log in the user with the following link (POST or GET), using the same parameters as to the call above:
http://www.supersaas.com/api/login?account=Your_acount_name&after=Schedule_url&user[name]=user@client.com&checksum=A4E67...DFEF
The API to the User database is RESTful.
It can be consumed by properly written libraries such as Ruby on Rails' Active Resource.
For each call you need to authenticate with the server by either adding your account and password as URL parameters or by using basic HTTP authentication.
For example: "http://supersaas.com/api/users?account=YourName&password=secret".
You can also use the MD5 checksum method outlined above. For additional security you can use SSL.
POST /api/users (SuperSaaS will assign a key)POST /api/users/{id} (You provide your own key in the format 9999fk)Location: http://www.supersaas.com/users/1234.xml.
If you want to find out the SuperSaaS ID (1234) of the created object you can extract it from this URL.
If the object did not pass validation, perhaps because of an invalid e-mail address, then status 422 ("Unprocessable Entity") will be returned, with the body of the response containing the error messages.
If you have provided your own key and the key already exists in the database, your call is assumed to be an update instead.
To avoid the create automatically being interpreted as an update you can add the parameter "duplicate=raise" and a status code 422 will be returned instead.
Note that if your booking ID contains a period you may need to call it as "/api/users?id={id}" to get it working correctly.
GET /api/users/{id}
/api/users?id=ab%25cd.
The response will be a 404 ("Not Found") or 200 ("OK") with the response body an XML document describing the user.
<user> ... </user>
GET /api/users
<users>
<user>
...
</user>
<user>
...
</user>
</user>
PUT /api/users/{id}
DELETE /api/users/{id}
The fields that you can supply are determined by the settings on the Access Control screen. Except for the user name all values are optional and will be set to a default value (usually blank) if not provided.
| Field | Comment | |||
|---|---|---|---|---|
| name | Required | The name of the user, max 50 bytes. If you selected to use e-mail addresses as login names then this has to be an e-mail address. | ||
| Optional | The e-mail address of the user. Ignored if you use the e-mail address as login name. | |||
| password | Optional | Password for the user, if you are using password login | ||
| full-name, address, mobile, phone | Optional | If any of these attributes are present they are stored unchanged as UTF-8 encoded strings | ||
| country | Optional | Either not present or a two character ISO 3166-1 country code | ||
| field-1, field-2, super-field | Optional | The values of the two custom fields and the supervisor field, irrespective of the display label you have given them in the user interface. | ||
| credit | Optional | Sets the credit level (default is 0). The format is selected on the Payment Setup screen. | ||
| role | Optional | Allowable values are 3: Regular user (default), 4: Superuser or -1: Blocked user | ||
| Field | Comment | ||
|---|---|---|---|
| id | The internal ID assigned to this user by SuperSaaS | ||
| fk | The ID assigned to this user by you if you supplied a foreign key | ||
| created-on | The time this user was created in UTC | ||
This example call using XML will create a new user record in the SuperSaaS user database. The record has database key 567 in your own database:
POST /api/users/567fk.xml
<?xml version="1.0" encoding="UTF-8"?> <user> <password>secret</password> <full-name>Full Name</full-name> <name>user@example.com</name> </user>
This would return a 201 ("Created") response with an empty body.
If you are instead using query parameters replace dashes with underscores in the field labels and write them as user[field]. You have to URI encode the values.
Example code for the same call, this time with query parameters:
POST /api/users/567fk?account=demo&password=secret&user[name]=user@example.com&user[password]=secret&user[full_name]=Full%20Name
user[field_1] in REST calls and <field-1> in XML calls.
Back to Tutorial index