SDK & Widget · Get started

Authentication

The SDK uses a two-step scheme: your API key opens a session, and a short-lived session token authorizes everything after that.

You need two values from your dashboard: the App ID, which identifies your Inboxi workspace, and an API key. The API key is used once per session, to call /api/widget/sdk/init. That call returns a session token that the client sends on every other SDK request.

Find your App ID and API key

inboxi.app/settings/developer
The Developer Hub holds your credentials, API keys, webhooks and the in-app developer docs.
  1. 1Settings › Developer Hub, under Platform API.
  2. 2Credentials & Setup shows your App ID (organization ID) and API key, with copy buttons.
  3. 3API Keys: create, revoke and delete keys.
  4. 4In-app quick reference for the website widget, Mobile SDK and push.
  1. 1
    Open the Developer Hub
    Go to Settings › Developer Hub.
  2. 2
    Copy your App ID
    The Credentials & Setup tab shows the App ID (your organization ID). It is safe to embed in public pages; the website widget only needs this value.
  3. 3
    Create an API key
    On the API Keys tab, create a key and copy it. Keys start with inx_live_. The key's secret is shown only once, at creation.

The authentication flow

API key
X-API-Key header
POST /sdk/init
Validates key, permission and plan
Session token
JWT, valid 24 hours
SDK calls
Authorization: Bearer <token>

1. Open a session with the API key

http
POST /api/widget/sdk/init
X-API-Key: inx_live_xxxxxxxxxxxxxxxx
Content-Type: application/json

The header X-Inboxi-API-Key is accepted as an alias. The key must be active, not expired, and carry the widget permission. See Init for the request body.

2. Use the session token everywhere else

http
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

The token is bound to one visitor (visitorId), your workspace, and the widget it was opened for. It is required by identify, messages, conversations and device-token.

Token expiry and renewal

  • Session tokens expire 24 hours after they are issued.
  • An expired token returns 401 with "code": "TOKEN_EXPIRED". Call /sdk/init again, passing the same userId so the visitor keeps their conversation, then retry the request.
  • The React Native SDK stores the token and re-initializes automatically when a saved session no longer works.
401: expired session
{
  "success": false,
  "error": "Session token expired. Call /api/widget/sdk/init to get a new token.",
  "code": "TOKEN_EXPIRED"
}

Rate limits

Calls authenticated with the API key (that is, /sdk/init) count against the key's per-minute limit, 60 requests per minute by default. Responses carry X-RateLimit-Limit and X-RateLimit-Remaining; a 429 also carries Retry-After in seconds. Because a session lasts 24 hours, a well-behaved client calls init once per app launch, not once per message.

Keeping your API key safe

Anything shipped in an app can be extracted
A key compiled into a mobile app or loaded in a browser can be read by a determined user. API keys created in the dashboard carry broad permissions by default (read, write, webhooks, widget, external_data), so treat a key embedded in a client as public.
  • Recommended for production apps: call /sdk/init from your own backend and hand only the returned sessionToken (and visitorId) to the app. The session token can only act as that one visitor and expires in 24 hours.
  • Use a dedicated key for each app so you can revoke one without breaking the others. Revoke a key from the API Keys tab the moment you suspect it leaked.
  • The website widget never needs an API key in your page: the loader only uses your App ID.
  • Never put an API key in a public repository. See API keys & permissions for the full permission model.