Authentication, Rate Limiting & Conventions

Base URL: https://your-openshopy-domain/api/public/v1

All endpoints except OPTIONS require an API key. The API version is part of the path (v1).

API keys

Two key types exist:

• Secret keys — os_sk_... — server-side only. Can use every scope granted to the key, including writes and sensitive reads (customers, orders, invoices, discounts, analytics).
• Publishable keys — os_pk_... — safe for browser/storefront code. They can only be created with the storefront scopes marked Yes in the table below. Endpoints that expose private data return 403 secret_key_required when called with a publishable key, even if the scope matches.

Keys can be revoked (revoked_at) or expire (expires_at); either makes the key invalid.

Sending the key

Send the raw key in one of:

Authorization: Bearer <key>

or

X-Api-Key: <key>

The Authorization header is checked first (must start with Bearer ); if absent, X-Api-Key is used. If neither is present: 401 unauthenticated.

The server looks up the SHA-256 hash of the key against api_keys.key_hash. If not found, revoked, or expired: 401 invalid_api_key.

Scopes

Every endpoint requires a scope (except GET /orders/track). If the authenticated key's scopes array does not include the route's scope: 403 insufficient_scope.

Routes with scope null (no scope check, but still require a valid key): GET /orders/track.

Rate limiting

Each key has a rate_limit_per_minute. Requests are counted per key in one-minute windows (default limit: 120 requests per minute, configurable per key from 10 to 5000).

Response headers on every request (success or error, once a valid key is matched):

X-RateLimit-Limit: <key.rate_limit_per_minute>
X-RateLimit-Remaining: <remaining, floored at 0>

When the limit is exceeded (remaining < 0):

HTTP/1.1 429
Retry-After: 60

{ "error": { "code": "rate_limited", "message": "Too many requests. Slow down and retry after the next minute.", "details": null } }

CORS

All responses (including the 401/403/404 error paths once routing starts) include:

Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, POST, PATCH, PUT, DELETE, OPTIONS
Access-Control-Allow-Headers: Authorization, Content-Type, X-Api-Key, X-Customer-Token, Idempotency-Key
Access-Control-Expose-Headers: X-RateLimit-Limit, X-RateLimit-Remaining, X-Request-Id
Access-Control-Max-Age: 86400

OPTIONS <any path> returns 204 with just the CORS headers (no auth required).

Note: Idempotency-Key is listed as an allowed request header for CORS purposes, but no route in the codebase reads or honors an Idempotency-Key header — there is no idempotency implementation server-side. Retries of POST requests (e.g. order/cart creation) are not deduplicated by the API itself.

Request logging

Every request made with a valid key is logged (visible in the dashboard under API keys → Request log) with: store_id, key_id, method, path (+ truncated query string, 200 chars), status, duration_ms, and ip (from cf-connecting-ip or x-forwarded-for).

Every response also carries X-Request-Id: <uuid>.

Pagination

List endpoints accept:

Response envelope for paginated endpoints:

{
  "data": [ /* array of resources */ ],
  "meta": {
    "page": 1,
    "limit": 25,
    "total": 134,
    "total_pages": 6
  }
}

Non-paginated endpoints return { "data": ... } with no meta, unless a handler sets custom meta (e.g. /taxes/rates includes meta: { prices_include_tax, store_country, destination_based }).

Error format

Every error response is JSON:

{
  "error": {
    "code": "not_found",
    "message": "Order not found",
    "details": null
  }
}

Validation errors (zod) return 422 with details as an array of { path, message }:

{
  "error": {
    "code": "validation_failed",
    "message": "Request body is invalid",
    "details": [{ "path": "email", "message": "Invalid email" }]
  }
}

Known error codes observed in the code:

Money format

All monetary amounts are integers in minor currency units (e.g. cents/grosze) — never floats. Example: 4999 = 49.99 in the order's currency. currency is always one of PLN, USD, EUR. Currency conversion between the store's base currency and the requested currency is done via store.exchange_rates (a flat multiplier map keyed by currency code — not a timestamped rate history).

Tax rates (tax_rates.rate) are decimal percentages, e.g. 23 for 23%, returned as a Number.

Dates

All timestamps are ISO 8601 strings, e.g. "2024-05-01T12:00:00+00:00". Query filters like created_after/created_before/updated_after on /orders accept ISO date/time strings and are passed straight to gte/lt.

Idempotency

Not implemented. The Idempotency-Key header is accepted by CORS but ignored by all handlers. Clients must implement their own deduplication (e.g. checking for an existing cart/order before retrying a POST).