Authentication

InsightCore uses two authentication models depending on the endpoint type.

Public Endpoints (No Auth)

The event collection and tag serving endpoints are intentionally public. They are called directly from end-user browsers and do not require authentication:

Endpoint	Auth	Protection
POST /v1/collect/{orgId}	None	Rate limiting (60/min per IP), domain validation
GET /v1/tag/rsp-analytics.js	None	ETag caching, CDN-friendly

Domain validation ensures events are only accepted from domains registered in your site configuration.

Authenticated Endpoints (OAuth Bearer)

All management and reporting endpoints require an OAuth 2.0 Bearer token from the Identity API:

Authorization: Bearer eyJhbGciOiJSUzI1NiIs...

Obtaining a Token

Use the client credentials grant to obtain a token:

curl -X POST https://identity.retailsuccessplatform.com/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=${CLIENT_ID}" \
  -d "client_secret=${CLIENT_SECRET}" \
  -d "scope=insightcore:settings.read insightcore:settings.write insightcore:reports.read insightcore:funnels.read insightcore:funnels.write"

Available Scopes

Scope	Description
insightcore:events.write	Send events via the server-side collection endpoint
insightcore:settings.read	Read site configurations
insightcore:settings.write	Create, update, and delete site configurations
insightcore:reports.read	Access historical reports and real-time analytics
insightcore:funnels.read	Read funnel definitions and analysis results
insightcore:funnels.write	Create, update, and delete funnel definitions

Organization Context

All authenticated requests are scoped to your organization. The organization is determined from the JWT token — you do not need to pass an organization ID on authenticated requests.

For platform-level access across multiple organizations, include the X-Organization-Context header:

curl https://api.insightcore.retailsuccessplatform.com/api/v1/analytics/reports/overview \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "X-Organization-Context: org_00000a1B2c3D4e5"

Rate Limits

Endpoint Group	Rate Limit
Event Collection (public)	60 requests/min per IP
Event Collection (authenticated)	1,000 requests/min
Site Settings	100 requests/min
Funnels	100 requests/min
Real-Time Analytics	100 requests/min
Historical Reports	100 requests/min

Rate limit headers are included in every response:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 97
X-RateLimit-Reset: 1711468800

Error Responses

401 Unauthorized — Missing or invalid token:

{
  "error": "unauthenticated",
  "message": "Valid authentication credentials are required."
}

403 Forbidden — Insufficient scope or accessing another organization's data:

{
  "error": "forbidden",
  "message": "You do not have permission to access this resource."
}

---

Changelog

Date	Change
2026-03-28	Added insightcore:events.write scope and authenticated event collection rate limit.
2026-03-26	Initial publication.