API Documentation

User Database Synchronization and Single Sign-On

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:

  1. You create a single "Book Now" button on your site that contains all relevant information for the person that is currently logged in on your site
  2. When the person clicks the button his information is posted to the SuperSaaS API, along with a checksum to prevent tampering
  3. If this is the first time the person is sent to SuperSaaS a new user account is created with the supplied information, otherwise his existing information is updated as needed
  4. The person will be automatically logged in and redirected to your schedule

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:

Create and Login

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.

Three options for the Database Key

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:

  1. You can provide your own unique 32 bit number. Typically the index key of your own user database is a good value to use. You indicate you are providing your own key by post fixing the ID with the letters 'fk' (foreign key).
  2. You can use the internal SuperSaaS user ID, which is also a 32 bit number. When you create a new record you have to retrieve and store that ID in your own database, and subsequently send it along it when you update that record.
  3. You can use the person's name as the key, any unique 50 byte string that does not start with a number. It is not a good idea to use something as a key if the person is allowed to change this value, since he would be disconnected from his bookings each time he changes it. If your own database key is something other than a 32 bit number you could repurpose this field to store your key.

Authentication with a MD5 Hash Checksum

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:

PHP: $user = 'user_name@client.com';$checksum = md5("Your_account_nameYour_account_password$user")
Ruby: 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.

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.

Log in only (without create)

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

Read, Create, Update and Delete Users

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.

Create a new user

POST /api/users   (SuperSaaS will assign a key)
POST /api/users/{id}   (You provide your own key in the format 9999fk)
The request should either contain an XML document describing the new user, or have the fields as URI encoded parameters. See the end of the document for the format. If the record is correctly created the response will be a header with status code 201 ("Created"). The Location field of the response header will contain the URL that you can use to retrieve the user later, e.g.: Location: http://www.supersaas.com/api/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.

Read one user

GET /api/users/{id}
If the ID is fully numeric it is assumed to be our key, otherwise it is considered to be your key. If the ID is alphanumeric it will be stored in the name field. Alphanumerical IDs can be provided as URI encoded parameters to avoid illegal characters in the URL, like so: /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>

Read all users

GET /api/users
This returns a 200 ("OK") with an XML document describing all users on your account. The number of records is limited to 100 unless you add a limit parameter such as "/api/users?limit=500".
<users>
   <user>
      ...
   </user>
   <user>
      ...
   </user>
</user>

Update a user

PUT /api/users/{id}
The system looks for the record with the given ID and updates it. Similar to the "create" API you can either provide an XML document or URI encoded parameters and the result will be a 200 ("OK") or a 422 with an error document. In case the record cannot be found the system assumes you want to do a create instead. To avoid automatically creating a new record you can add the parameter "notfound=error" or "notfound=ignore" to return a 404 ("Not Found") or 200 ("OK") respectively. If you are trying to use a SuperSaaS internal key that doesn't exist a 404 ("Not found") is always returned. If the software you are using does not support sending of the HTTP PUT verb then you can simply do a regular POST instead.

Delete a user

DELETE /api/users/{id}
The system will look for the ID in the database and return a 200 ("OK") if the record was deleted successfully, or a 404 ("Not found") if it (no longer) exists. If the software you are using is not able to send the HTTP DELETE verb then you can also do a POST with the extra parameter "_method=DELETE"

Data Format

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.

FieldComment
nameRequiredThe 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.
emailOptionalThe e-mail address of the user. Ignored if you use the e-mail address as login name.
passwordOptionalPassword for the user, if you are using password login
full-name, address, mobile, phoneOptionalIf any of these attributes are present they are stored unchanged as UTF-8 encoded strings
countryOptionalEither not present or a two character ISO 3166-1 country code
field-1, field-2,
super-field
OptionalThe values of the two custom fields and the supervisor field, irrespective of the display label you have given them in the user interface.
creditOptionalSets the credit level (default is 0). The format is selected on the Payment Setup screen.
roleOptionalAllowable values are 3: Regular user (default), 4: Superuser or -1: Blocked user

When reading data the retrieved XML document will contain the following fields in addition to the ones listed above:
FieldComment
idThe internal ID assigned to this user by SuperSaaS
fkThe ID assigned to this user by you if you supplied a foreign key
created-onThe time this user was created in UTC

Illustrative Usage

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
You would send your account name and password in the header using basic HTTP authentication and send the following body:
<?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

Troubleshooting tips


Back to Tutorial index