Quickstart

Your first API call in five minutes: get a key, confirm it's wired, then read the catalog. Every snippet is copy-paste-runnable - paste your sandbox key and go. You never send a tenant_id; the merchant is resolved from the key.

1. Get a sandbox key

Ask your Harmon admin to issue a publishable key for your store, or grab one yourself from the admin API keys screen. For exploring, start with a sandbox key - it has the hk_test_ prefix and can never touch live commercial data.

→ Get your API keys

A publishable key (hk_*_pub_…) is browser-safe and authorizes anonymous catalog reads. A secret key (hk_*_sec_…) is server-side only and unlocks customer-scoped reads, checkout, and webhooks. See Authentication & keys for the full split.

2. Confirm the key is wired - GET /v1/ping

GET /v1/ping echoes the resolved merchant, the key kind, the granted scopes, and the mode without touching any data - the fastest way to prove your key works.

Paste your key once and every snippet on this page rewrites to use it:

Paste your API key once

Stored only in this browser, never sent anywhere but the API. Every snippet on the page rewrites to use it.

curl -s https://api.harmon.example/v1/ping \
  -H "Authorization: Bearer hk_test_pub_your_key_here"

A success looks like:

{
  "tenant_id": "t_demo",
  "key_kind": "PUBLISHABLE",
  "scopes": ["storefront:catalog"],
  "mode": "sandbox"
}

Confirm "mode": "sandbox" before you experiment - see Sandbox vs live.

3. List products - GET /v1/products

Anonymous catalog reads work with the publishable key. Paginate with page / page_size; the response carries a strong ETag you can revalidate against (see Pagination & caching):

curl -s "https://api.harmon.example/v1/products?page=1&page_size=5" \
  -H "Authorization: Bearer hk_test_pub_your_key_here"

Each product carries a coarse availability band (IN_STOCK / LOW / OUT), never a raw on-hand count - see Availability.

Next steps

• Authentication & keys - the capability split and shopper tokens for customer-scoped reads and checkout.
• Pagination & caching - keep a local catalog fresh with ETag and updated_since.
• API Reference - every operation, parameter, and schema, with a live Try-it console.

In the API Reference

Open these operations in the interactive reference (with a Try it console):

• GET /v1/ping - check your key + mode
• GET /v1/products - list the catalog