Some V3 API methods are "HMAC protected" and thus require an HMAC Authorization header.

The API reference documentation states whether an API method requires a HMAC Authorization header.

Using HMAC protected API methods presupposes that the client is registered within 52eSELLER. The registration involves exchanging a private key ("secretKey") that must be used to access HMAC protected API methods.

The secretKey exchange will be done differently depending on the trust level of the application:

• Low level of trust: The secretKey will be returned directly by the API.
• High level of trust: The secretKey must be manually looked up in the shop administration and entered in the application as part of the registration flow.

Trust is tied to the device on which the app is running, and the inherent target audience for the app.

An app with a low level of trust is an app downloaded by a consumer, that can be used right away.

An app with a high level of trust is an app to which the shop administrator has direct access and thereby can actively permit (or deny) access to an app, that requires elevated API access.

Currently only API methods requiring a low trust level exist – namely the logs API methods.

Registration flow

When an app lifecycle begins, the app must register with 52eSELLER by requesting the "hello" API method, supplying a valid apiKey and registrationSecret. The apiKey and registrationSecret are maintained in the 52eSELLER shop administration.

POST services/v3/auth/hello

In return, it receives an installationId. If the app has a low level of trust, the API also returns a secretKey directly in the response. If the app has a high trust level, the secretKey must be manually looked up in the shop administration and communicated (e.g. by phone or e-mail). If a registrationToken is supplied in the "hello" request, it can be used to identify the appropriate API secretKey in the shop administration.

Both the installationId and secretKey must be stored in the client and used to access HMAC protected API methods.

NOTE: Registration should only occur when the app lifecycle begins – that is, when the app is first started upon installation. On each app start up, it is good practice to verify that the registration is still valid. This is done by making a request to the "verifyhello" endpoint including the apiKey and installationId.

POST /services/v3/auth/verifyhello 

Generating the HMAC Authorization header

To use HMAC protected API methods, the request must include an Authorization header, with "hmacauth" as type, followed by a string for identification and authentication.

Authorization hmacauth <hmac string>

The <hmac string> itself consists of a series of tokens, separated by colon (":"). These tokens identify the request and enables the server to verify the authenticity.

Example of such header

Authorization: hmacauth MD5/SHA256:52Eseller:91d29475-702b-4189-bf6d-4f554e275760:tXa5IY1ia5KdD2LAXNbUYunOt+A2qKS763qmKnHDKtM=:9ncyCAfCb1m0veK03vWVly7KOt6ICSE8:1614586389

The individual parts are:

[hashmethods]:[apikey]:[installationid]:[signature]:[nonce]:[timestamp]

• [hashmethods]
  • Defines what hashing algorithms are used for hashing the content body, and what hashing is used for hashing the signature. Both methods are separated with a forward slash ("/")
  • Valid values are:
    • MD5
    • SHA1
    • SHA256
    • SHA512
• [apikey]
  • This is the apiKey that is created by the shop administrator.
• [installationid]
  • Identifies a particular installation of an app.
  • For apps with low trust level, this is returned in the response from the API.
• [signature]
  • This is the signature of the request. The signature is concatenated by the following parts (with no separators) in this particular order:
    • [apikey]
    • [installationid]
    • [http method] - i.e. GET, PUT POST, PATCH, DELETE
    • [URL] EXCEPT for schema – that is: everything before "//", for instance "https://". Example value: www.myshop.com/services/v3/logs
    • [hash] A base64-encoded hash of the content body in the used content body encoding, using the selected body hashing algorithm. When hashing, you must use the secretKey.
    • [nonce] A unique string, that must vary for each request in order to prevent replay attacks. A request with an identical value to a previous request will be rejected.
    • [timestamp] A unix timestamp (epoch - seconds since 1970/01/01-00:00:00) that helps preventing replay attacks.
  • After string concatenation, the signature must be hashed with the selected signature hashing algorithm and base64-encoded. When hashing, you must use the secretKey.
• [nonce]
  • A unique string, that must vary for each request in order to prevent replay attacks. A request with an identical value to a previous request will be rejected.
• [timestamp]
  • A unix timestamp (epoch - seconds since 1970/01/01-00:00:00) that helps preventing replay attacks.