Understanding API Security


 

Overview

For security reasons, it is important that all method calls to the CloudBilling API are secure. This is achieved via a combination of transport-level security (SSL) and a custom, token-based authentication mechanism.

API Tokens

With the release of CloudBilling 1.11, we now support API tokens in addition to username/password logins. These long-lived tokens are created through the Management Portal. These will eventually replace the current username/password logins. API tokens are submitted for every request to the API in the SOAP header. The namespace to use for the header is http://api.cloudbilling.nl/2018/11/auth/token and the name to use for the element is ApiToken.

Username Password

The first step in order to authenticate yourself against the CloudBilling API, is to make a login request (via the Login method) containing a valid set of user credentials.

User credentials consist of an email address, password and environment, and should correspond to a valid CloudBilling user account.

The second step in order to authenticate against the CloudBilling API, is to interpret the login response status. Success would indicate authentication had succeeded, while an error status would indicate that authentication was unsuccessful.

There may be a number of reasons why authentication would fail. Details may be found in the optional status message that is returned as part of the login response, but some common scenarios can include:

  • Invalid user credentials
  • Locked user account
  • Insufficient account privileges

It is worth noting that a locked user account may result due to too many invalid login attempts.

Currently, a user account will be locked for a period of 15 minutes upon the third incorrect login attempt. 

Once locked due to invalid login attempts, a user account can only be unlocked by an administrator or by a subsequent, successful login where correct credentials are supplied.

The final step in order to authenticate against the CloudBilling API, is to interpret the login response value. A successful login attempt would yield an access token (also referred to as an authentication token) which has to be supplied as part of the header for all secure method calls.

Authentication tokens have a limited life-span, which may vary according to numerous factors. This is not something that can be accurately predicted and should not be relied upon for any reason. Since tokens may thus expire at any time, the correct way to consume service methods would be to always check the response status for all method results and log in again if a new authentication token is required.