Authentication

API authentication is handled by signing each request using your ShippingEasy account's public API key and private API secret (found here).

How to calculate a signature

First, concatenate these into a plaintext string using the following order:

1. Capitalized method of the request. E.g. "POST"
2. The URI path
3. The query parameters sorted alphabetically and concatenated together into a URL friendly format: param1=ABC¶m2=XYZ (Note: parameter values here should be URL encoded. For example, if you are sending a timestamp as a last_update_at parameter it should look like last_updated_at=2022-12-10T19%3A38%3A25.000-00%3A00)
4. The request body as a string if one exists
5. All parts are then concatenated together with an ampersand. The result resembles something like this:

API Signature String

"POST&/partners/api/accounts&api_key=f9a7c8ebdfd34beaf260d9b0296c7059&api_timestamp=1401803554&{"{\"account\":{\"first_name\":\"Coralie\",\"last_name\":\"Waelchi\",\"company_name\":\"Hegmann, Cremin and Bradtke\",\"email\":\"[email protected]\",\"phone_number\":\"1-381-014-3358\",\"address\":\"2476 Flo Inlet\",\"address2\":\"\",\"state\":\"SC\",\"city\":\"North Dennis\",\"postal_code\":\"29805\",\"country\":\"USA\",\"password\":\"abc123\",\"subscription_plan_code\":\"starter\"}}"

Secondly, using your API secret encrypt the string using HMAC sha256. In ruby, it looks like this:

Calculating the API signature in Ruby

OpenSSL::HMAC::hexdigest("sha256", api_secret, "POST&/partners/api/accounts&api_key=f9a7c8ebdfd34beaf260d9b0296c7059&api_timestamp=1401803554&{"{\"account\":{\"first_name\":\"Coralie\",\"last_name\":\"Waelchi\",\"company_name\":\"Hegmann, Cremin and Bradtke\",\"email\":\"[email protected]\",\"phone_number\":\"1-381-014-3358\",\"address\":\"2476 Flo Inlet\",\"address2\":\"\",\"state\":\"SC\",\"city\":\"North Dennis\",\"postal_code\":\"29805\",\"country\":\"USA\",\"password\":\"abc123\",\"subscription_plan_code\":\"starter\"}}")
  

If you find your API requests being rejected due to signature verification mismatch with a 401 status code, the most frequent cause is due to small differences in the the concatenated plaintext value provided to the HMAC function to generate the signature.

The API Credentials page (found here) includes a tool to help debug issues with the signatures you generate. With it you can capture an API request to compare signatures and view the plaintext value the ShippingEasy server used for your request to generate the expected signature to spot any differences with your implementation. You’ll want to ensure the plaintext value you used for signature verification is identical to what the ShippingEasy server is using or the signatures won’t match.

📘

API Timestamp

You must include an API timestamp in your requests. The timestamp should be an integer representation of the current time (also known as Unix epoch time).