Authentication

All API requests require authentication via a Bearer token in the Authorization header.

Making authenticated requests

Include your API key in the Authorization header:

curl https://app.simpleproductfeeds.com/v1/shop \
  -H "Authorization: Bearer spf_live_sk_a1b2c3d4e5..."

API key format

API keys follow this format:

spf_live_sk_ + 40 hexadecimal characters

Example: spf_live_sk_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0

The spf_live_sk_ prefix identifies the key as a Simple Product Feeds live secret key. Keys are shown in full only once — at creation time. After that, only the prefix is visible in the dashboard.

Scopes

Each API key has one or more scopes that control what it can access. When creating a key, choose the minimum scopes your integration needs.

Scope	Description
full_access	Read and write all resources
read	Read all resources
write	Write all resources (implies read)
read_settings	Read shop and feed settings
write_settings	Write shop and feed settings
read_feeds	Read feed configuration and status
read_exports	Read export history and sync status
write_exports	Trigger syncs and exports
read_products	Read source and feed products
write_products	Write product data
read_rules	Read feed transformation rules
write_rules	Create, update, and delete rules
read_channels	Read channel connections and datafeeds
write_channels	Manage channel connections and datafeeds
read_subscription	Read plans and subscription status
write_subscription	Create and cancel subscriptions
read_webhooks	Read webhook configurations and deliveries
write_webhooks	Create, update, and delete webhooks
read_admin	Read admin-only resources (admin keys only)
write_admin	Write admin-only resources (admin keys only)

Scope hierarchy

Broader scopes automatically include narrower ones:

• full_access grants all scopes
• write grants all write_* and read_* scopes
• read grants all read_* scopes

For example, a key with read scope can access any endpoint requiring read_settings, read_feeds, read_exports, read_products, read_rules, read_channels, or read_subscription.

Idempotency

For non-GET requests, you can include an Idempotency-Key header to safely retry operations without performing them twice. If you send the same idempotency key within 24 hours, the API returns the cached response from the original request.

curl -X POST https://app.simpleproductfeeds.com/v1/syncs \
  -H "Authorization: Bearer spf_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: my-unique-request-id-123" \
  -d '{"type": "full"}'

How it works

• Include an Idempotency-Key header (max 64 characters) on any POST, PATCH, or DELETE request.
• The first request is processed normally and the response is cached.
• Subsequent requests with the same key return the cached response with no side effects.
• Keys are scoped to your API key — different API keys can use the same idempotency key independently.
• Cached responses expire after 24 hours.
• Server errors (5xx) are never cached — you can safely retry with the same key.
• The Idempotency-Key header is echoed back in the response.

When to use it

Idempotency keys are especially useful for:

• Triggering syncs — prevent duplicate syncs if a network timeout causes a retry.
• Creating webhooks — avoid duplicate subscriptions.
• Updating products — ensure a batch update isn’t applied twice.

GET requests are inherently idempotent and do not require this header.

---

Rate limit headers

Every API response includes rate limit headers so you can track your usage without waiting for a 429 response:

Header	Description
X-RateLimit-Limit	Maximum requests allowed per window.
X-RateLimit-Remaining	Requests remaining in the current window.
X-RateLimit-Reset	Unix timestamp when the current window resets.

Merchant API keys are limited to 120 requests per minute. Admin API keys are limited to 60 requests per minute. Unauthenticated requests are limited to 20 requests per minute per IP. See Rate Limiting for details.

Error responses

If authentication fails, the API returns a 401 Unauthorized response:

{
  "error": {
    "type": "authentication_error",
    "message": "API key is missing. Include it in the Authorization header as: Bearer <your-key>",
    "code": "key_missing"
  }
}

See Errors for all authentication error codes.