API Security

API Security

Whispir's API supports multiple methods of authentication to cater for varying client needs.  Authentication is necessary for users of the API to ensure that only valid and legal requests are processed by the Whispir messaging engine.

When accessing Whispir's API, the user has the option of using either of the following authentication methods:

  • Basic authentication over HTTPS (default)

These authentication mechanisms will be available to all customers when initially setting up the account.  Users will then be able to manage the security settings through the standard Mashery interface.

Basic Authentication

The basic authentication process is offered for use with clients that already have an ‘up and running’ application, and would like to integrate Whispir as a messaging provider in a quick and simple fashion.

Basic access authentication over HTTPS involves the application client sending an encoded Username and Password with when requesting resources from the server.

Clients will also be required to provide the API Key that is provided when the application is registered within Mashery.  This API Key is used to determine the application that is making the request, and whether it is allowed to make requests, it is still within the request thresholds, and is a valid API Key. 

Once this has been confirmed, the request is forwarded on to Whispir for Basic authentication processing.

  • If this Username and password is correct, the server will process the request and send back an appropriate response.
  • If the Username and password is not correct, the server will send back an HTTP 401 (Authorization required).

Basic Authentication


Once Whispir has validated the username and password, the requested resource is returned through Mashery to the application client.

The Basic authentication model over HTTPS provides a relatively secure interface into Whispir's API platform, but is susceptible to ‘Man in the Middle’ attacks.  It is recommended that all application clients implement the OAuth authentication (release Q1 2013) to have a more sophisticated security model within the application.

Basic Authentication – Example

A valid request that will be accepted and authenticated by the Whispir messaging engine using Basic authentication is as follows:

HTTP 1.1 GET /workspaces/123/contacts?firstname=John&lastname=Smith?apikey=789264
Authorization: Basic frJIUN8DYpKDtOLCwo//yllqDzg=

The ‘Authorization’ header is comprised of the word Basic followed by the base64 representation of the username and password of the user.

More information about HTTP Basic Authentication can be found on Wikipedia.