Get started

Getting started

This page walks through the minimum needed to issue a request against the Mercentia gateway.

Auth

Every API call carries one of:

  • A session cookie (better-auth.session_token) — set by the dashboard sign-in flow. Use this when the caller is a logged-in staff user in the browser.
  • A bearer API key (Authorization: Bearer sf_live_…) — for server-to-server / partner integrations. Issue keys from Settings → API Keys in the dashboard.

API keys carry typed scopes. The full catalog is exported from @mercentia/shared/scopes and surfaced at GET /api/v1/api-keys/scopes. Use the narrowest scope that lets the integration work; avoid the top-level write wildcard outside of admin tooling.

Tenant headers

Most endpoints require an x-store-id header identifying which of the caller’s stores the request is for. Some admin endpoints also accept x-org-id. The dashboard reads these from localStorage and echoes them on every request; partner integrations should set them explicitly.

A request that touches an RLS-protected table without x-store-id will return zero rows or 404 — never another tenant’s data. See the RLS runbook for the policy model.

Hello, Mercentia

curl -i \
  -H "Authorization: Bearer sf_live_xxx" \
  -H "x-store-id: 11111111-1111-4111-8111-111111111111" \
  https://api.mercentia.com/api/v1/products?limit=1

Expected: HTTP/1.1 200 OK with a single product row in the envelope.

Idempotency

Every action-framework endpoint accepts an optional caller-supplied request id used to derive the idempotency key. Two attempts for the same (orderId, requestId) collapse into the first one’s result — safe to retry on transient failure.

What to read next