Docs / Authentication

Secure your API integrations with scoped tokens

Create tokens in the app admin, store them in your secret manager, and send them as Bearer credentials on every request.

View endpoint reference Install app first

Authentication checklist

Create a token in API Access inside the embedded app.
Grant only the scopes your integration needs.
Store the token in a secure secret manager.
Handle 401, 403, and 429 responses in your client logic.

Auth header

Send bearer tokens in Authorization

Every API request should include `Authorization: Bearer YOUR_TOKEN`. Missing or malformed tokens return `API_TOKEN_UNAUTHORIZED` (401). Missing required scopes return `API_TOKEN_FORBIDDEN` (403). The `GET /api/v1/auth-status` endpoint is intentionally safer: it only verifies the presented token and returns safe introspection fields without plan checks or `lastUsedAt` writes.

Request example

curl -X GET https://your-locaprice-domain.com/api/v1/auth-status \
  -H "Authorization: Bearer YOUR_TOKEN"

Scopes

Scope mapping

Scope	What it enables
`locations:read`	Read synced Shopify location records.
`prices:read`	Read location prices, location groups, price rules, catalog lookups, and resolution endpoints.
`prices:write`	Create, update, and delete pricing data (including rules/groups), plus trigger runtime checks.
`sync:write`	Reserved for sync workflows. Keep for forward compatibility when creating broad integration tokens.

Rate limiting

Plan for safe retries

Rate-limited endpoints apply a sliding window policy of 100 requests per 60 seconds per token prefix. On limited responses, use `Retry-After` and the returned `X-RateLimit-*` headers before retrying.

Error payload shape

{
  "ok": false,
  "error": {
    "code": "API_TOKEN_FORBIDDEN",
    "message": "Insufficient API token scope."
  }
}