Get a partner key

Every call carries your key. This page is the part of the guide about keys: what each kind opens, what sandbox means, what to check before go-live, and whom to ask.

Auth

Send your key on every GraphQL and MCP call:

X-Partner-Key: <key we issue you>

Today the catalog also answers without a key: products, categories and branches (the anonymous-catalog policy is still open). Anything with a basket, order, payment or earnings needs the key.

A key has a scope:

• Merchant keys (full) open everything above.
• Catalog keys (catalog) are for teams that only need product data. They open the product info API and read-only catalog queries: products, product, categories, branches, inventory, search, searchSuggest, fulfilmentResolve, and the MCP catalog tools. Mutations, baskets, orders, earnings and the assistant answer with a scope error.
• Guest keys (guest) are publishable keys for a sandbox basket without sign-in, such as a public demo page. They open everything a catalog key opens, plus guestSession and the basket (basket, basketAdd, basketRemove, basketSetQuantity, basketSetBranch, basketEmpty). guestSession returns a guest token (vgt_…, valid 24 hours) and an ownerId of the form guest:…; send the token as Authorization: Bearer <guest token> with the same key. Quotes, orders, payment, earnings and the assistant answer with a scope error, and a guest key never accepts a shopper's Cognito token. Guest baskets expire after two days.
• Events keys (events) are for a search partner measuring its own results. On GraphQL they open only the basketEvents query (see Basket events); every other field answers with a scope error.

The key maps to your partnerId and registered orderSource (stamped on quotes and orders).

Shopper-scoped operations (basket, quote, order, payment) also need the customer’s Cognito id token:

Authorization: Bearer <shopper idToken>

For a shopper, ownerId is always the bare Cognito sub from a verified id token (a guest's is guest:…, from the signed guest token). Do not invent it. Unsigned or forged tokens are rejected.

Shoppers sign up and sign in against the platform's shopper pool (email and password, a six-digit code by email). Your app talks to Cognito directly with the pool's public app client id, which we give you with your key; GET /shop does exactly this in about fifty lines of JavaScript. Baskets and orders belong to your key and that shopper together — the same shopper signed in through another partner has a different basket and sees none of your orders.

Sandbox vs production

Live money requires: partner key issued, Cognito app client for your redirect URIs, fulfilment branch resolve confirmed, payment + order webhooks registered.

Go-live checklist

• [ ] Partner key issued; orderSource registered
• [ ] Cognito client + redirect URIs for your shop domain
• [ ] Fulfilment resolve tested for your delivery postcodes
• [ ] Quote → order → paymentStart sandbox closed
• [ ] Webhook URL verified (HMAC)
• [ ] Production key rotated; no test in specialComment

Support

Engineering vault (public contracts): https://knowledge.villamarket.ai
Ask for a partner key: contact Villa Market AI / partner onboarding.