Security and Rate Limits

Public guard behavior, origin validation, subscription checks, and throttling expectations.

Audience: Security-conscious integration teams and operators managing public runtime reliability.

Critical: Public site endpoints are guarded by site verification, origin checks, and subscription validation before processing requests.

Auth and Permissions Errors and Retries Client API Advanced Configuration

Who This Page Is For

Use this page when implementing resilient client behavior against 403/429 responses and validating public endpoint security assumptions.

Quick Start (2-5 Minutes)

Understand public guard checks

Public endpoints validate siteKey, site verification, origin/referer, and subscription.

PublicSiteGuard enforces these checks before controller execution.

Map throttled endpoints

Event and order ingestion have additional throttling controls.

events/batch uses visitor throttle; orders use stricter order throttle.

Handle rate-limit headers

Read X-RateLimit-* and Retry-After headers on throttled responses.

Implement exponential backoff and dedup where applicable.

Avoid origin mismatches

Send requests from verified storefront domain context.

Origin/referer must match configured site domain.

Operationalize retries

Treat 429 and 5xx as retry candidates with bounded policies.

See /reference/errors-and-retries for recommended behavior.

Protect tokenized email tracking links

Email open/click/unsubscribe endpoints rely on signed tracking tokens.

Do not construct these URLs manually; use renderer-generated links only.

Required Fields / Minimum Payload

Field	Required	Type	Used by events	Description
`siteKey`	Required	`string`	Public site endpoints	Public site identifier for guard lookup.
`origin/referer headers`	Conditional	`headers`	Guarded public endpoints	Validated against site domain.
`x-selwise-api-key`	Conditional	`header`	Originless mobile runtime requests and API-only tenant newsletter subscribe endpoint	Required when origin/referer is unavailable for mobile runtime auth, and for POST /public/sites/:siteKey/newsletter/api/subscribe.
`X-RateLimit-Limit/Remaining/Reset`	Conditional	`response headers`	Throttled endpoints	Expose throttle window and remaining capacity.
`Retry-After`	Conditional	`response header`	429 responses	Seconds to wait before retry.
`email tracking token`	Conditional	`signed string`	Public email open/click/unsubscribe endpoints	Token is validated for signature, type, siteKey, and expiration.

Key public endpoints and throttling notes

GET    /api/v1/public/sites/:siteKey/config
GET    /api/v1/public/sites/:siteKey/tracking-config
POST   /api/v1/public/sites/:siteKey/events/batch   # visitor throttled
POST   /api/v1/public/sites/:siteKey/orders         # stricter order throttle + duplicate order protection
GET    /api/v1/public/sites/:siteKey/search
GET    /api/v1/public/sites/:siteKey/widgets
GET    /api/v1/public/sites/:siteKey/campaigns
POST   /api/v1/public/sites/:siteKey/newsletter
POST   /api/v1/public/sites/:siteKey/newsletter/confirm
GET    /api/v1/public/sites/:siteKey/newsletter/confirm?token=...
POST   /api/v1/public/sites/:siteKey/newsletter/api/subscribe   # x-selwise-api-key required
GET    /api/v1/public/sites/:siteKey/email/open/:token
GET    /api/v1/public/sites/:siteKey/email/click/:token
GET    /api/v1/public/sites/:siteKey/email/unsubscribe?token=...

Email tracking endpoints (/public/sites/:siteKey/email/*) are token-validated using signed links. They are not visitor/order throttled routes and do not rely on JWT.

Tenant newsletter model:

Browser widget flow writes tenant-scoped audience contacts via /public/sites/:siteKey/newsletter without admin/global newsletter sender dependency.
API-only subscribe flow (/public/sites/:siteKey/newsletter/api/subscribe) does not require origin matching but requires a valid, non-revoked site public API key and explicit consent in payload.
/public/sites/:siteKey/newsletter/confirm endpoints are legacy compatibility endpoints for pending-token flows.
Newsletter API-only keys are managed at /api/v1/email/public-api-keys* and use newsletter_subscribe scope.
Mobile runtime keys are managed at /api/v1/sites/:siteId/public-api-keys* and use mobile_read / mobile_write scopes.

Originless Mobile Fallback Sequence

When origin and referer are absent, public guard logic follows mobile key validation:

Resolve site from siteKey.
Validate site.isVerified.
Resolve required scope from HTTP method.
Validate x-selwise-api-key for site + scope.
Validate subscription.
Execute controller action.

Scope mapping:

GET -> mobile_read
POST, PUT, PATCH, DELETE -> mobile_write

Event or Endpoint Decision Matrix

Scenario	Use This	Why
Need secure public runtime access	Public site guarded endpoints	Site/origin/subscription checks enforced centrally.
Need high-volume event tracking	events/batch + rate-limit aware client	Handles scale with throttle protections.
Need transaction ingestion	orders endpoint with dedup-safe behavior	Stricter fraud/abuse controls for orders.
Need originless mobile runtime access	Scoped `x-selwise-api-key` auth	Enables React Native clients without referer/origin headers.
Need diagnosis of forbidden responses	Validate site verification and origin domain	Most common 403 root causes.
Need resilience against temporary throttling	Backoff using Retry-After and X-RateLimit headers	Prevents repeated 429 spikes.

Common Errors and Fixes

403 Site not verified

Cause: Site exists but verification not completed.

Fix: Complete site verification flow in site management.

403 Origin validation failed

Cause: Origin/referer does not match configured site domain.

Fix: Send requests from approved storefront domain context.

429 Too Many Requests on events/batch

Cause: Visitor throttle limit exceeded.

Fix: Back off using Retry-After and reduce duplicate bursts.

400 Invalid unsubscribe/open/click token

Cause: Token is expired, malformed, or signed with different secret.

Fix: Regenerate links from current campaign renderer and validate EMAIL_TRACKING_SECRET consistency.

409 Duplicate Order

Cause: Same orderId submitted multiple times in throttle window.

Fix: Implement idempotent order submission and dedup logic client-side.

Production Checklist

Public requests originate only from verified storefront domains.Required
Client handles 429 and Retry-After headers correctly.Required
Email tracking links are renderer-generated and not client-forged.Required
Order submission flow is idempotent by orderId.Required
Monitoring tracks 403/429/409 trends by endpoint.Required
Incident runbook includes guard and throttle diagnostics.Required