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 it changed
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.

<form method="post" action="https://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.

Authentication for booking widgets

Via the widget configuration page you add schedule that appears integrated into your site, either inside a frame or as a button that shows it when clicked. If your users are already logged into your own website, it’s possible to automatically log them into the widget as well so they do not need to log in a second time.

After configuring the widget, an HTML snippet is shown at the bottom of the widget configuration page and can be copied into your site’s HTML. By adding another script tag on the page above the widget snippet, you can set the following JavaScript globals to be used by the widget for built-in API authentication:

Your API authentication configuration script tag should look similar to this:

<script>
  // This is an example, replace with generated values
  var supersaas_api_user_id = "1234fk";
  var supersaas_api_user = {"name":"my_username","full_name":"","phone":"","address":""};
  var supersaas_api_checksum = "1a79a4d60de6718e8e5b326e338ae533";
</script>

So if you generate the above script via your site’s server-side programming language with real data from the currently logged-in user, then their account will be automatically created or updated as soon as the widget loads. The created or updated user will then be automatically logged in inside the widget as well.

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

Please first refer to the Authentication Page.

There is no need to provide the user’s password this way since the form is already authenticated with the checksum. You can send a user password, and it will be stored, but it is better not to do so because 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 it won’t be updated until he uses the above button again. Also, a user that you delete from your own database will not be removed from the SuperSaaS database. Usually, the slightly outdated information is no reason for concern because it gets updated on the next visit. However, if you want to keep the SuperSaaS in sync 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. As an aside, the reverse is also possible, you can set a webhook to send a message to your server each time the information changes on SuperSaaS, but it’s often easier to simply disallow the user to make changes to his own information while on the SuperSaaS site.

Log in only (without create)

If the request contains an “Origin” header then the server will add appropriate CORS headers. This will allow the request to be sent from an AJAX call inside a browser. It’s highly recommended sending any request from the browser via an SSL encrypted (https) connection.

Integration with booking widgets (without automatic account creation)

With the databases in sync, if you use on of our scheduling widgets on your site, you can add a simple script tag setting the following JavaScript globals with data from your currently logged-in user anywhere on the page before the other widget script tags, and the user will be automatically logged in inside the widget too as soon as it loads:

The script tag should look similar to this:

<script>
  // This is an example, replace with generated values
  var supersaas_api_user = {"name":"my_username"};
  var supersaas_api_checksum = "1a79a4d60de6718e8e5b326e338ae533";
</script>

So if you generate the above script via your site’s server-side programming language with real data from the currently logged-in user, then the user will be automatically logged in inside the widget too as soon as it loads.

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 name and api_key as URL parameters or by using HTTP Basic Authentication. For example: https://supersaas.com/api/users?account=YourName&api_key=api_key. You can also use the MD5 checksum method outlined on the authentication page. 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 XMLJSON document describing the new user, or have the fields as URI encoded parameters. See below for the data 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: https://www.supersaas.com/api/users/1234.xmljson. If you want to find out the SuperSaaS ID (1234) of the created object, you can extract it from this URL.

If the object fails 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.

When you provide 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 username, all values are optional and will be set to a default value (usually blank) if not provided.

Illustrative Usage

<?xml version="1.0"?>
<user>
   <full-name>Full Name</full-name>
   <name>user@example.com</name>
</user>

{
  "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.

In the above example we’ve used the MD5 checksum as authentication. This avoids the need to send the api_key in clear text, which can pose a security problem.

Read one user

<user>
   ...
</user>

{
  "id": "123456",
  "name": "example",
  "email": "example@gmail.com",
  ...
}

Read all users

<users>
   <user>
      ...
   </user>
   <user>
      ...
   </user>
</users>

[
  {
    "id": "123456",
    "name": "example",
    "email": "example@gmail.com",
    ...
  },
  {
    "id": "789123",
    "name": "example2",
    "email": "example2@gmail.com",
    ...
  }
]

Show forms

When a form is attached to a user, you can show the form’s data by adding the form=true parameter to the URL. The output will be the same as the Form API.

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 XML document, a JSON document or use URI encoded parameters.

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.

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.

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.

Troubleshooting tips