Authentication

Ordergroove's APIs support two versions of authentication:

Application API Scope - Authentication via an x-api-key header that uses one of 10 keys available for your store. These keys (up to 10 per merchant) should only be used for server-to-server requests and not exposed on the client side.

• Within Application API Scope, some keys may be granted the permission for "Bulk Operations". This means the key will be able to return records across multiple customers when using the List endpoints. Without this permission, the key will only return records within the scope of a single customer.

Storefront API Scope - Authentication via a generated signature to call Ordergroove's APIs straight from the client within the context of a single customer. The key itself should not be exposed on the client side.

• Within Storefront API Scope, you can optionally provide a parameter called "trust_level": recognized in the header of your request. This can be used when the customer is in a recognized state but not fully logged into your site, and limits the given signature to a small subset of available actions.

Application API Scope

All requests use HTTP Basic Auth and must be made over HTTPS. Calls made over plain HTTP and calls without authentication will fail.

Be sure to keep your keys secure, and only provide Application API keys to users that you trust.

Here is an example built in JavaScript:

const axios = require("axios"); // npm install axios

const url = "https://restapi.ordergroove.com/subscriptions/";
const headers = {
  "x-api-key": "<REPLACE_ME_WITH_APPLICATION_API_KEY>",
};
const params = {
  customer_id: "<REPLACE_ME_WITH_CUSTOMER_ID>",
};
axios
  .get(url, { headers, params })
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error);
  });

Storefront API Scope

All requests use HTTP Basic Auth and must be made over HTTPS. Calls made over plain HTTP and calls without authentication will fail.

Never expose the Storefront API Key itself, but rather use a generated signature to communicate with Ordergroove's APIs from the client.

Here is an example built in JavaScript:

const axios = require("axios"); // npm install axios
const CryptoJS = require("crypto-js"); // npm install crypto-js

// Constants
const MERCHANT_ID = "<REPLACE_ME_WITH_MERCHANT_ID>";
const STOREFRONT_API_KEY = "<REPLACE_ME_WITH_STOREFRONT_API_KEY>";

// This function generates the OG Authorization header for a given customer
const generateOGAuthorization = (customerId) => {
  const ts = Math.floor(new Date().getTime() / 1000);
  const hash = CryptoJS.HmacSHA256(`${customerId}|${ts}`, STOREFRONT_API_KEY);
  const sig = CryptoJS.enc.Base64.stringify(hash);
  return JSON.stringify({
    public_id: MERCHANT_ID,
    sig_field: customerId,
    ts,
    sig,
  });
};

// Test the header generation
const customerId = "<REPLACE_ME_WITH_CUSTOMER_ID>";
const url = "https://restapi.ordergroove.com/subscriptions/";
const headers = {
  "Content-Type": "application/json",
  Authorization: generateOGAuthorization(customerId),
};
axios
  .get(url, { headers: headers })
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error);
  });

Key Retrieval and Sample Code

To retrieve the keys for your store as well as view code snippets in additional languages, please visit https://rc3.ordergroove.com/keys/.