Mobile Auth

Header Contract

@selwise/react-native sends:

x-selwise-api-key
x-selwise-client-platform: react-native (default)
x-selwise-client-version: <sdk_version>

Guard Behavior

Public endpoints support two access modes:

Browser/Web mode

When origin or referer exists, domain validation runs.

Mobile mode

When origin and referer are absent, x-selwise-api-key is validated.
Required scope is selected by HTTP method:
- GET -> mobile_read
- POST/PUT/PATCH/DELETE -> mobile_write

Scope Catalog

SitePublicApiKeyScope:

newsletter_subscribe
mobile_read
mobile_write

Key Management Endpoints

Site-scoped mobile key operations:

GET /api/v1/sites/:siteId/public-api-keys
POST /api/v1/sites/:siteId/public-api-keys
POST /api/v1/sites/:siteId/public-api-keys/:keyId/rotate
POST /api/v1/sites/:siteId/public-api-keys/:keyId/revoke

Manual-Origin Controller Fallback

These controllers also accept originless mobile access through key+scope validation:

POST /api/v1/public/sites/:siteKey/users/identify
POST /api/v1/public/sites/:siteKey/users/traits
POST /api/v1/public/sites/:siteKey/consent
DELETE /api/v1/public/sites/:siteKey/consent

Error Scenarios

Status	Scenario	Typical Cause	Fix
`403`	Invalid API key	Missing/revoked/wrong key	Rotate or recreate key and update mobile app secret.
`403`	Insufficient scope	Read key used for write endpoint	Add `mobile_write` scope or use correct key.
`403`	Origin validation failed (web mode)	Domain mismatch	Verify domain and request origin alignment.
`404`	Site not found	Wrong `siteKey`	Use correct site key for current environment.

Request Example (Originless Mobile)

POST /api/v1/public/sites/SITE_KEY/users/identify HTTP/1.1
Host: api.selwise.com
Content-Type: application/json
x-selwise-api-key: swpk_live_xxxxx
x-selwise-client-platform: react-native
x-selwise-client-version: 0.1.2

{
  "externalId": "user_42",
  "visitorId": "vid_123",
  "sessionId": "sid_123"
}

Metadata Enrichment

When mobile client headers are present, tracking metadata is enriched with:

sdkPlatform
sdkVersion

This applies to event ingestion, consent-related tracking events, recommendation/search analytics events, and order metadata.

Operational Recommendations

Keep separate keys for staging and production.
Use least-privilege scope per app.
Rotate keys periodically and immediately on leak suspicion.
Never hardcode keys in source.