Authentication

How to authenticate a Binoban request: which credentials you need, how to send them yourself over REST, how the SDKs send them for you, and which APIs currently require them.

Credentials

Binoban issues two credentials per data source when the source is set up — apiKey and sourceIdentifier. There is no self-serve token endpoint and no OAuth exchange — send both on every authenticated request. Alongside them, every SDK/REST integration also needs an apiHost to know where to send requests; it isn't issued per source (it's the same host for every source in your environment), which is why it's listed separately below.

Credential	What it is	Where it goes
apiKey	A secret bearer token, unique per source.	Authorization: Bearer <apiKey> header
sourceIdentifier	A 12-character public source handle.	URL path segment
apiHost	The API host for your environment — api.binoban.io in the cloud, or your tenant's on-prem host.	Request host

info

Never send these as writeKey — that name is an internal alias and isn't part of the public contract. Use apiKey and sourceIdentifier.

Send the header

Authenticate Tracking and Sync requests by sending your apiKey as a Bearer token, with your sourceIdentifier in the URL path:

curl --location 'https://{apiHost}/api/tracker/sdk/{sourceIdentifier}/track' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer {apiKey}' \
  --data-raw '{
      "userId": "123",
      "event": "order_completed"
  }'

Replace {apiHost} with your environment's API host, {sourceIdentifier} with your source's 12-character identifier, and {apiKey} with your source's API key. Event names must match ^[a-zA-Z0-9_\-.]*$ — snake_case, no spaces.

How the SDKs authenticate

If you integrate with a Binoban SDK instead of calling REST directly, you don't build the header yourself. Each SDK takes apiKey and sourceIdentifier at initialization, then attaches the Authorization: Bearer <apiKey> header (and the sourceIdentifier path segment) to every request it sends on your behalf. The host story differs by SDK — see the caution below.

SDK	Where the credentials go
Web SDK	The load snippet's credentials: { apiKey, sourceIdentifier }. Host is a separate, optional host: { apiPath, sdkPath, rtbPath, metricPath } object — apiPath is where events are sent, sdkPath is where the snippet fetches the SDK bundle itself; see the Web SDK how-to.
Native SDK (Android / iOS)	The client constructor / factory, with a required apiHost. See the Native SDK.
React Native	createClient — per-platform { apiKey, sourceIdentifier } plus a top-level, required apiHost. See the React Native SDK.

The Web SDK and the Native SDK handle the host differently

The Native SDK and the React Native bridge ship no fallback host, on either platform — apiHost is a required config field; a blank value initializes the client in a disabled (no-op) state and sends nothing. The Web SDK is different: it takes host.apiPath (not apiHost) and falls back to a built-in default host if you omit it. Set host.apiPath explicitly for on-prem or air-gapped deployments.

Where Bearer auth applies

Bearer authentication is required for the Tracking API and the Sync API — every /api/tracker/sdk/{sourceIdentifier}/... and /api/tracker/catalog/{sourceIdentifier}/... request must carry a valid Authorization: Bearer <apiKey> header, or it's rejected.

RTB authentication

The Ad Request API (POST /api/rtb/ad) and Sponsored Ads API (POST /api/rtb/sponsoredAd) do not currently require an Authorization header — source identity for these requests travels inside the request body instead of a Bearer token. This is a known gap: authenticating RTB requests the same way as Tracking/Sync is a pending product decision, not yet scheduled. Don't build a dependency on RTB being unauthenticated — treat it as subject to change.

Getting credentials

apiKey and sourceIdentifier are issued by Binoban when a data source is created — there's no public signup or key-generation endpoint. If you need a new source, lost your apiKey, or need to rotate a compromised one, contact Binoban. Credential issuance and rotation are handled out-of-band today, not self-serve.

Errors

Status	Code	Cause
401	error.sdk.authorization.failed	The Authorization header is missing, malformed, or the apiKey doesn't match the source.
404	error.sdk.source.notFound	The sourceIdentifier is missing, malformed, or doesn't resolve to a known source.

Both are returned as a JSON array of { field, message } objects. For these two errors the field is an empty string — read the message code to tell them apart:

[
  { "field": "", "message": "error.sdk.authorization.failed" }
]