Authentication — API

API keys

A key looks like mk_live_ followed by 40 characters, and it belongs to exactly one store. It is presented in the X-Api-Key header — and it is read only by POST /v1/auth/anonymous and POST /v1/auth/refresh. Every other endpoint ignores it and wants a bearer token instead.

Keep the key on your server. It should never ship inside a browser bundle or a mobile app binary.
The key is shown once when issued; matgrk stores only a hash of it.
Each key carries its own rate limit, counted per minute.
A session minted with a key can only be refreshed with that same key — revoking the key ends its sessions at their next refresh.

Access and refresh tokens

POST /v1/auth/anonymous mints a token pair for the key’s store. Access tokens live 15 minutes and go in the Authorization: Bearer header; refresh tokens live 30 days and are single-use — each refresh consumes the presented token and issues a new pair. A refresh token that is replayed is refused.

Mint a token pair

curl -X POST https://api.matgrk.com/v1/auth/anonymous \
  -H "X-Api-Key: mk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"transport": "bearer", "scope": ["catalogue:read", "cart:write"]}'

Rotate it

curl -X POST https://api.matgrk.com/v1/auth/refresh \
  -H "X-Api-Key: mk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"refreshToken": "REFRESH_TOKEN"}'

Cookie transport

Pass "transport": "cookie" instead and the tokens are set as httpOnly, secure cookies — the response body then carries no token at all, so page scripts can never read one. Refreshing with the cookie needs no body.

Scopes

A token carries the scopes it was minted with, and every endpoint checks one declared scope. Asking for scopes at mint time can only narrow the default set — an undeclared name is refused, and a call outside the token’s scopes gets 403 INSUFFICIENT_SCOPE.

catalogue:readRead products, categories and brands
search:readSearch suggestions and search context
cart:readRead the current cart
cart:writeCreate and change carts
checkout:writeQuote, choose fulfilment and place orders
account:readRead the shopper profile and addresses
account:writeRegister, sign in and manage addresses
orders:readRead the shopper’s orders

Shopper sessions

Every session starts anonymous. The /v1/account/* endpoints — register, sign-in, one-time codes — attach a shopper to the session, and the shopper’s cart, addresses and orders follow it from there.