Authentication

3 Minutes to read

Print
Share
Dark
Light

Article summary

Did you find this summary helpful?

Thank you for your feedback

API Key and Shared Secret

Mapp's API Authentication framework allows developers to manage access rights of external applications that integrate with their account on the Empower Enterprise platform.

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

Field	Description	Example
api_key	Uniquely identifies your account as the one associated with 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', the response will be an XML-formatted message. When response_type is set to 'PHP', 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 methods calls results in 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 Empower 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 for which the client account is enabled. As new API methods are introduced, this setting automatically gives this API User access to those future methods. This is the typical setting for simple integrations between the Mapp 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 Empower Enterprise platform, and security control is a concern. The methods displayed in the list only correspond to the different modules 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).

Access Level

Description

Full

This setting grants the API User access to all API methods for which the client account is enabled. As new API methods are introduced, this setting automatically gives this API User access to those future methods.

This is the typical setting for simple integrations between the Mapp 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 Empower Enterprise platform, and security control is a concern.

The methods displayed in the list only correspond to the different modules 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 Empower Enterprise with their API Key and Shared Secret pair (a.k.a. "API User") must have their IP addresses whitelisted with the platform to make a method call successfully. This also means that if you created multiple API Users, each must include the whitelisted IP addresses in their respective profiles. The same IP address(es) can 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 Empower 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 your system will use to access Empower Enterprise.

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

127.0.0.0-127.255.255.255

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>

Was this article helpful?

What's Next

Calling An API Method

Table of contents

API Key and Shared Secret
Whitelisting Your System's IP Address