Documentation
Print page

User API

The user API allows you to create, read, update and delete users from your account. It also has specialized methods to log in a browser while creating or updating a user object at the same time. 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.

The API accepts data as URL parameters, as JSON or as XML, and can return data as either JSON or XML.

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 it 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, if needed
  4. The person will be automatically logged in to SuperSaaS 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:

  • On the Access Control page, under the heading Who can create a login name?, select Log in and registration managed on your site.
  • Uncheck the option Use email address as login name, unless your site uses email addresses as login name.
  • Under What information should the user enter when creating a login name, select fields as appropriate. You can switch off Password. Although you can synchronize passwords too, there is no need since login takes place elsewhere.
  • You will also want to check the option Prevent users from updating their own information so your own database stays in the lead.
  • On the Layout Settings page make sure Your URL is filled out. Should people somehow end up at SuperSaaS without logging in at your site first, they will be sent there.

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 when you update that record.
  3. You can use the person’s name as the key or any other 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 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 a predetermined 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 the user in 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 Users API

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 HTTP Basic 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

To create a new user, you need to send an HTTP POST request to /api/users.json. The request should either contain an JSON document describing the new user, or have the fields as URI encoded parameters. See below for the data format.

POST /api/users   (SuperSaaS will assign a key)
POST /api/users/{id}   (You provide your own key in the format 9999fk)

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.json. 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 email address, then status code 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 a create action from being automatically interpreted as an update, you can add the parameter duplicate=raise. In that case a status code 422 will be returned instead. Note that if your booking ID contains a period (.), you may need to use the id parameter (/api/users?id={id}) to get it to work correctly.

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 email addresses as login names then this has to be an email address.
emailOptionalThe email address of the user. Ignored if you use the email 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 on the configuration pages.
creditOptionalSets the credit level (default is 0). The format is selected on the Payment Setup screen.
roleOptionalAllowed values are:
3: Regular user (default)
4: Superuser
-1: Blocked user

When reading data the retrieved JSON 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 JSON, 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.json
You would send your account name and password in the header, using HTTP Basic Authentication and send the following body:
{
  "password": "secret",
  "full_name": "Full Name",
  "name": "user@example.com"
}

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_name]. All values need to be URI encodes as well.

Example code for the same call, this time with query parameters:
POST /api/users/567fk.json?account=demo&password=secret&user[name]=user@example.com&user[password]=secret&user[full_name]=Full%20Name

Read one user

GET /api/users/{id}.json
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.
{
  "id": "123456",
  "name": "example",
  "email": "example@gmail.com",
  ...
}

Read all users

GET /api/users.json
This returns a 200 OK with an JSON 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.json?limit=500.
[
  {
    "id": "123456",
    "name": "example",
    "email": "example@gmail.com",
    ...
  },
  {
    "id": "789123",
    "name": "example2",
    "email": "example2@gmail.com",
    ...
  }
]

Update a user

To update a user, you need to send an HTTP PUT request to /api/users, specifying the ID of the user in question. Similar to creating a user, you can either provide an JSON document or use URI encoded parameters.

PUT /api/users/{id}.json

The system looks for the record with the given ID and updates it. The result will be 200 OK or a 422 Unprocessable Entity 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 status is 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

Deleting a user can be done by sending an HTTP DELETE request to /api/users, specifying the ID of the user in question.

DELETE /api/users/{id}

The system will look for the ID in the database and return 200 OK if the record was deleted successfully, or 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.

Troubleshooting tips

  • If you see an error Email is not a valid email address, then please refer to the Settings section on this page to confirm you have made the correct settings in your SuperSaaS account
  • If the button redirects the user but does not appear to actually log him in, then the cookie gets lost somewhere along the way. The most common cause is that the domain you are using to access the API is different from the domain of the schedule you are sending the user to; they should be the same.
  • If you allow people on your site without logging in, you probably want to ensure that they can not access the automatic login to SuperSaaS. Your code probably would not generate a valid login for anonymous users, but if it does then all anonymous users would be able to see and change each other’s appointments. If you want to be able for anonymous users to see the schedule before asking them to log in, you could provide a regular link for them to the schedule instead.
  • If you get the error Bad request – unknown attribute: field-1, then you used the variable name with a dash instead of an underscore in a POST call. So you should use user[field_1] in REST calls and <field-1> in XML calls.