APIs and tokens
Choose credentials and client libraries for each surface. Every request includes X-Tenant-Id. Server integrations use API keys or HMAC private tokens; browser integrations use HMAC public tokens with a restricted write surface.
API base URLs
| Engine API base URL | Admin UI |
|---|---|
| https://api.recomnext.com | https://admin.recomnext.com |
Use the engine base URL as baseUrl in widgets and SDKs.
Authentication options
| Setting | Type | Default | Description |
|---|---|---|---|
| X-Api-Key | header | — | Server-side API keys. Broad access per route policy. |
| HMAC private | signed requests | — | hmac_timestamp, hmac_sign, body_hash query params. Server SDKs. |
| HMAC public | signed requests | — | frontend_timestamp, frontend_sign. Browser SDK and widgets. |
| JWT | Bearer | — | Admin UI only — not for storefront integration. |
HMAC vs API keys
| Setting | Type | Default | Description |
|---|---|---|---|
| Expose in browser | — | — | API key: never. Public HMAC: yes (origin-restricted). |
| Bulk catalog upsert | — | — | API key / private HMAC: yes. Public HMAC: no. |
| Log interactions | — | — | All schemes supported on ingestion endpoints. |
| Fetch recommendations | — | — | All schemes on recommendation endpoints. |
| Manage scenarios | — | — | API key only (admin/ops). |
| Token rotation | — | — | Public HMAC: 24h grace for previous token after rotate. |
Public HMAC allowed writes
Browser tokens may POST only to: ingestion interactions, impressions, identity merge, unified recommendations, and items-to-items legacy POST.
Widgets vs SDKs vs raw API
| Setting | Type | Default | Description |
|---|---|---|---|
| Widgets | @recomnext/carousel | — | Drop-in carousel, auto impressions, minimal code. |
| Browser SDK | @recomnext/browser | — | Custom UI, recommend(), trackView, mergeIdentity. |
| Node SDK | @recomnext/node | — | Full API, batch ingestion, scenario CRUD. |
| REST | curl / any HTTP | — | Maximum control; you handle auth and retries. |
Marketing site — fastest launch
Use the vanilla carousel script with data-scenario and data-public-token. See Widgets Guide.
<div data-recomnext-carousel data-base-url="https://api.recomnext.com" data-tenant-id="aurora-games" data-scenario="homepage-for-you" data-logic="user-to-item" data-count="8" ></div>
React storefront — custom cards
Browser SDK with recommend() and renderItem equivalent via your components.
import { RecomnextBrowserClient } from '@recomnext/browser';
const recomnext = new RecomnextBrowserClient({
baseUrl: 'https://api.recomnext.com',
tenantId: 'aurora-games',
publicToken: 'rnx_pub_...',
});
const { items } = await recomnext.recommend({
scenario: 'homepage-for-you',
userId: 'customer-42',
count: 8,
includedProperties: ['attributes.name', 'attributes.price', 'attributes.coverUrl'],
});Backend catalog pipeline
Node SDK with API key for nightly sync and interaction backfill.
import { RecomnextClient } from '@recomnext/node';
const client = new RecomnextClient({
baseUrl: 'https://api.recomnext.com',
tenantId: 'aurora-games',
apiKey: process.env.RECOM_API_KEY,
});
await client.ingestion.upsertItems(batch);Backend interaction backfill (no scenario)
Import historical orders or browse events from your warehouse. scenarioSlug is optional — omit it when the source event was not from a recommendation slot.
await client.ingestion.logInteractions([
{ userId: 'customer-42', itemId: 'game-elden-ring', type: 'view' },
{ userId: 'customer-42', itemId: 'bundle-starter', type: 'purchase', weight: 4 },
]);Integration patterns
Browser-direct
Public token in SDK/widget. Configure allowed origins on the token. Lowest latency; token visible in bundled JS (origin-bound, not secret like an API key).
BFF / server proxy
Browser calls your API; your server holds the API key or private token. Use when security policy forbids any engine credential in the browser. You own caching and rate limits.
// Your BFF route
const response = await fetch('https://api.recomnext.com/recommendations', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'X-Tenant-Id': 'aurora-games',
'X-Api-Key': process.env.RECOM_API_KEY,
},
body: JSON.stringify({ scenario: 'homepage-for-you', userId, count: 8 }),
});