authentication

‹ BACK TO API PAGE


Description

API Key and Shared Secret

BlueHornet's API Authentication framework gives developers the flexibility to manage access rights of external applications that integrate with their account on the eMS Enterprise platform.

The XML elements contained within the authentication element contain the account information associated wiith the API method call. Each of the elements are listed in the table below:

Field Description Example
api_key Uniquely identifies your account as the one associatedwith this API method call. 2a6035671daba0f771c82346f2d9ddf8
shared_secret Acts as the password to authenticate the API method call c5f596647ca11369
response_type Allows you to choose the format of the response data. Currently, the two choices are:
  • xml
  • php

When response_type is set to 'xml', then the response will be an XML-formatted message. When response_type is set to 'php', then the response will be a PHP array.

no_halt A boolean value that when set to '1', instructs the system to continue processing all method calls contained in a single POST in the case where any of the method calls results in an error. The default value is '0'. Read more about error reporting. 1

At least one API Key and Shared Secret pair must exist for proper authentication. For simplicity of management, API Key and Shared Secret pairs are encapsulated as an "API User" complete with a user name for convenient reference. To manage (and create) API Users, log in to eMS Enterprise as an Admin user and then navigate to Administration > API Settings > Manage API Users.

Each API Key and Shared Secret pair must be assigned one of the following three access levels within the application:

Access Level Description
Full This setting grants the API User access to all API methods that the client account is enabled for. As new API methods are introduced, this setting automatically grants this API User access to those future methods as well.

This is the typical setting for simple integrations between the BlueHornet platform and a single external system where the same API Key and Shared Secret pair will be used for all system integrations.

Custom This setting provides the developer with fine-grained access control and allows him to restrict the methods that can be called using this particular API Key and Shared Secret.

This setting is typically used in cases where multiple external systems are integrating with the eMS Enterprise platform and/or security control is a concern.

The methods displayed in the list are only those corresponding to the different modules that the client account is enabled to use.

3rd Party Integration This setting is available only if the client account is enabled for integration either with SalesForce.com or with SeeWhy (which uses the Real-Time Triggered Messaging platform for real-time cart abandonment emails).

Whitelisting Your System's IP Address

All external systems connecting to eMS Enterprise with their own API Key and Shared Secret pair (a.k.a. "API User") must have their IP addresses whitelisted with the platform in order to successfully make a method call. This also means that if you created have more than one API User, each will need to include the whitelisted IP addresses in their respective profiles. It is possible for the same IP address(es) to be listed in the API IP Whitelist section of two or more API User profiles.

To whitelist an IP address or a range of addresses, log in to eMS Enterprise as an Admin user and then navigate to Administration > API Settings > Manage API Users. Next, select the API User representing the API Key and Shared Secret pair that your system will be using to access eMS Enterprise.

In the API IP Whitelist section, enter the IP addresses of your systems that you want eMS Enterprise to whitelist. You can enter individual addresses or a range of addresses. eMS Enterprise supports the following notation for IP address ranges:

     127.0.0.0-127.255.255.255

or

     169.254.0.0/16

IP addresses associated with the standard 3rd party integrations listed above are automatically whitelisted and will be reflected in this section.

API calls made with an IP address that has not been whitelisted
will return the following error:

<methodResponse>

<item>

<error><![CDATA[1]]></error>

<responseText><![CDATA[Invalid Request IP: Please add request_ip to

the API Whitelist in your account. (Account -> Edit Account: API Tab)]]></responseText>

<responseData>

<request_ip><![CDATA[208.79.252.143]]></request_ip>

</responseData>

<responseNum><![CDATA[1]]></responseNum>

<totalRequests><![CDATA[1]]></totalRequests>

<totalCompleted><![CDATA[0]]></totalCompleted>

</item>

</methodResponse>


Back to API Reference Guide