How does REST API authentication work?

REST API requests authenticate with a per store Bearer key that you generate in the Wishlist Hero admin. This page covers key lifecycle, the exact request shape, how requests are validated, and the errors you will see.

Available on Gold Plus plans and above.

Generate a key

1. In the app, open Settings > REST API access for third party integrations.
2. Click Generate API Key.
3. Copy the key immediately and store it in your secret manager. The admin shows it once; the app keeps only a hash.

Replace API Key issues a new key and invalidates the old one at the same moment. Use it on suspicion of leakage and update your integrations in the same deploy.

The request shape

curl "https://your-api-base/api/v1/your-store.myshopify.com/Wishlist/your_wishlist_hash/items" \
  -H "Authorization: Bearer your_api_key_here"

Three credentials ride on every call:

• The key in the Authorization: Bearer  header
• The store domain in the path, which scopes all data to that store
• The wishlist hash in item routes, which scopes to one shopper’s list

How validation works

On every request the API checks, in order:

1. A key is present: otherwise 401
2. The key matches the store: otherwise 401
3. The store’s plan includes the REST API: otherwise 403 with “Upgrade Your Plan”
4. The store is active and the app is not disabled: otherwise 403

There is no OAuth flow and no per user token: the key is a store level secret. Treat it like a password; it grants full wishlist read and write for the store.

Keys live per store

• One active key per store
• Keys are stored hashed, so support cannot recover a lost key: generate a replacement
• Rotating a key is atomic: the old key stops working the moment the new one is created

Error handling in your client

const res = await fetch(url, { headers: { Authorization: `Bearer ${apiKey}` } });
if (!res.ok) {
  if (res.status === 403) throw new Error("REST API not enabled for this plan");
  if (res.status === 401) throw new Error("Invalid API key");
}

Branch on 401  and 403  separately: the first means your key handling is wrong, the second means billing or store status, and the fixes differ.