Every call to the API must be authenticated, which must be done by adding a custom HTTP header (X-WSSE) with your API user name and secret.
In order to keep your API secure, Account Owners can create new API users and matching secret keys regularly in the Security Settings page of the Admin menu.
Here are a few code samples in different languages that you can use to test the authentication:
The header has the following format, usually a single HTTP header line which we have broken down into multiple lines for easier readability:
X-WSSE: UsernameToken Username="customer001", PasswordDigest="ZmI2ZmQ0MDIxYmQwNjcxNDkxY2RjNDNiMWExNjFkZA==", Nonce="d36e316282959a9ed4c89851497a717f", Created="2014-03-20T12:51:45Z"
- X-WSSE - The name of the HTTP header we use for authenticating the request.
UsernameToken - The authentication method, and must contain a
UsernameTokenas we only support token-based authentication.
- Username - This field contains the username you were provided during onboarding. It is usually in the following format: account_name00X, where X is a digit.
- PasswordDigest - This field contains the hashed token which will prove the authenticity of your request. It is essential that you recompute this hash for every request as a hash is only valid for a certain period of time, and then it expires. You can read more about how to compute below.
- Nonce - A random value used to make your request unique so it cannot be replicated by any other unknown party. This string is always 16 bytes long and should be represented as a 32 characters long hexadecimal value.
- Created - This field contains the current UTC, GMT, ZULU timestamp (YYYY-MM-DDTHH:MM:SS) according to the ISO8601 format, e.g. `2014-03-20T12:51:45+01:00`. You can use any timezone you want as long as it is defined in the timestamp, but recommend that you use UTC time as this is the global Emarsys standard.
- If no timezone is provided, Emarsys server’s timezone is assumed, which is GMT+1. Under these circumstances, the timestamp “2014-01-01T01:01:01” would be translated to “2014-01-01T01:01:01+01:00”. During daylight saving time, Emarsys server’s timezone is GMT+2.
- The Created timestamp must be within five minutes of the Emarsys server’s time. If it is not within the specified timeframe, the request will be rejected. We recommend using NTP to synchronize your time.
- The following timezone formats are accepted and considered the same:
Computing the Password Digest
Computing the password digest involves 5 simple steps:
- Get a randomly generated 16 byte Nonce formatted as 32 hexadecimal characters.
- Get the current Created timestamp in ISO8601 format.
- Concatenate the following three values in this order: nonce, timestamp, secret.
- Calculate the SHA1 hash value of the concatenated string, and make sure this value is in hexadecimal format! Some languages, like PHP, output hexadecimal hash by default. You may need to use special methods to obtain hexadecimal hashes in different languages or even convert byte to hex values by hand (see the sample codes below for more information).
- Apply a BASE64 encoding to the resulted hash to get the final PasswordDigest value.