Authentication & Rate Limits

Every request to the Flxpoint API carries a single token in the X-API-TOKEN header. There are three token types — Account, Source, and Channel — each with a different scopeWhat the token is allowed to doA token's scope is the set of endpoints and resources it can hit. Account tokens have the broadest scope; Source / Channel tokens are deliberately narrow so a leak doesn't expose the whole workspace. and its own rate-limit bucketEach token tracks its own 2-req/s budgetRate limits are per token, not per account. If you have 5 Source tokens and one Account token, that's 6 separate 2-req/s buckets — 12 req/s aggregate. They never share or steal from each other..

Biggest source of 401 errors: using the wrong token type. An Account token isn't a superset of Source / Channel tokens — each type is scoped to specific endpoints. One support ticket traced 7,000 failed requests to a single mismatch before it was caught. The token matrix below shows which token you need per resource.

The request header

All requests use the same header. Do not use Authorization: Bearer — that's a common mistake when porting client code from other APIs.

X-API-TOKEN: YOUR_TOKEN

A complete request:

curl -X GET "https://api.flxpoint.com/account" \
  -H "Accept: application/json" \
  -H "X-API-TOKEN: YOUR_TOKEN"

Token types

Account token

Workspace-wide access. Use for admin work and for endpoints that cross resource boundaries. Account tokens cannot perform source-scoped or channel-scoped operations — those are intentionally excluded for blast-radius reasons.

Source token

Scoped to a single Source (a supplier / warehouse / 3PL). Use when you're integrating as a supplier: pushing inventory, acknowledging fulfillment requests, reporting shipments. Each source has its own 2 req/s bucket — 10 sources with their own tokens effectively give you 20 req/s aggregate.

Channel token

Scoped to a single Channel (a marketplace / storefront / POS). Use when you're pushing orders in, pulling listings to publish, or syncing shipment status back out.

Token → endpoint matrix

Pick a token type below to see only what it can touch. When in doubt, send with a Source or Channel token first — an Account token on a scoped endpoint returns 401 Unauthorized or 403 Forbidden.

Per-operation scope is the source of truth — see the API reference for the exact security block on each endpoint.

Rate limits

2 requests per second, per token. That's a rolling limit — burst traffic above 2 req/s in any 1-second window returns 429 Too Many Requests.

The Retry-After header

When you get a 429, the response includes a Retry-After header with the number of seconds to wait. Honor it. Retrying before the window clears just adds to the queue and can compound the problem.

HTTP/1.1 429 Too Many Requests
Retry-After: 1
Content-Type: application/json

{"error":"Too many requests","data":{"limit":2,"window":"1s"}}

Recommended retry pattern

Exponential backoffWait longer between each retry — 1s, 2s, 4s, 8s...Instead of retrying immediately (which keeps you over the limit), you double the wait between each retry. This gives the server time to recover and prevents stampedes when many clients retry at once. with jitterA small random offset added to each waitIf 100 clients all back off by exactly the same amount, they all retry at the same instant — and the server gets hammered again. Adding a small random offset (e.g. ±30%) spreads the retry traffic out so no single second sees a wave., capped at a sensible max. Don't retry non-429 errors the same way — 401 / 403 / 4xx validation errors will never succeed on retry.

async function flxRequest(url, opts, maxRetries = 4) {
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    const res = await fetch(url, opts);
    if (res.status !== 429) return res;

    const retryAfter = Number(res.headers.get("retry-after") ?? 1);
    // exponential backoff with jitter, capped at 16s
    const backoff = Math.min(retryAfter * 2 ** attempt, 16);
    const jitter = Math.random() * 0.3 * backoff;
    await new Promise(r => setTimeout(r, (backoff + jitter) * 1000));
  }
  throw new Error("Rate-limited after " + maxRetries + " retries");
}

Scaling throughput legally

The rate limit is per token, not per account. Two ways to scale:

• One token per source / channel. 10 source integrations with dedicated tokens = 20 req/s aggregate. This is the intended path.
• Batch where possible. Endpoints like POST /inventory/parents accept up to 20 parents per call; PUT /inventory/variants accepts 50. A batch call counts as one request.

What you should not do: hammer Flxpoint from a tight loop to "poll as fast as possible". Several customers have crashed their own server infrastructure by polling aggressively in both directions. See Polling fulfillment requests for the right pattern.

Errors you'll see

Quick health check

Before building anything, confirm the token works:

curl -v "https://api.flxpoint.com/account" \
  -H "X-API-TOKEN: YOUR_TOKEN"

A 200 with your account JSON means you're in. A 401 means the header or token is wrong — don't proceed until that returns 200.

Related

• Date formatting — every datetime in requests and responses uses ISO 8601.
• Integrating as a Source — the full Source-side flow.
• Integrating as a Channel — the full Channel-side flow.
• Polling fulfillment requests — how to avoid rebuilding Flxpoint's state locally.