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&param2=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:
"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:

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\"}}")

📘

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).