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 url = "https://restapi.ordergroove.com/subscriptions/";

const headers = {
  "x-api-key": "<REPLACE_ME_WITH_APPLICATION_API_KEY>",
};

const queryString = new URLSearchParams({
  customer: "<REPLACE_ME_WITH_CUSTOMER_ID>",
});

// Make the GET request with fetch
fetch(`${url}?${queryString}`, { headers: headers })
  .then((response) => {
    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`);
    }
    return response.json();
  })
  .then((data) => {
    console.log(data); // Logs the data received from the API
  })
  .catch((error) => {
    console.error("Error:", 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:

// 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
async function generateOGAuthorization(customerId) {
  const ts = Math.floor(Date.now() / 1000);
  const encoder = new TextEncoder();
  const keyData = encoder.encode(STOREFRONT_API_KEY);
  const messageData = encoder.encode(`${customerId}|${ts}`);

  // Import the key for HMAC-SHA256
  const key = await crypto.subtle.importKey(
    "raw",
    keyData,
    { name: "HMAC", hash: "SHA-256" },
    false,
    ["sign"]
  );

  // Sign the message
  const signature = await crypto.subtle.sign("HMAC", key, messageData);

  // Convert to Base64
  const sig = btoa(String.fromCharCode(...new Uint8Array(signature)));

  return JSON.stringify({
    public_id: MERCHANT_ID,
    sig_field: customerId,
    ts,
    sig,
  });
}

// Test the header generation
async function fetchData() {
  const customerId = "<REPLACE_ME_WITH_CUSTOMER_ID>";
  const url = "https://restapi.ordergroove.com/subscriptions/";

  try {
    const authHeader = await generateOGAuthorization(customerId);
    const headers = {
      "Content-Type": "application/json",
      Authorization: authHeader,
    };

    const response = await fetch(url, { method: "GET", headers });

    if (!response.ok) {
      throw new Error(`HTTP error! Status: ${response.status}`);
    }

    const data = await response.json();
    console.log(data);
  } catch (error) {
    console.error(error);
  }
}

// Call the function
fetchData();

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