SDK sessions API

Generated from api/openapi.public.yaml, the same spec the API serves. Try these operations in the API console; errors are Problem Details.

Exchange a publishable key and a user token for an SDK session

POST /api/v1/sdk/sessions

The publishable key’s origin and app restrictions apply, and each user token is accepted once. The session acts as the workspace member the user maps to, within the scopes of the secret key that signed the token. A partner’s publishable key is exchanged only on the partner’s sites; its session acts as the user’s membership of each store the token lists, and each new membership takes a seat in its store (no_free_seat names a store without one).

Operation id	createSdkSession
Authentication	None: the request body carries what the operation needs.

Parameters

Name	In	Type	Required	Description
X-Ios-Bundle-Identifier	header	string		iOS apps: the app’s bundle id, checked against the key’s allowed bundle ids
X-Android-Package	header	string		Android apps: the app’s package name, checked against the key’s allowed packages

Request body

application/json: CreateSessionInputBody

Field	Type	Required	Description
embedOrigin	string		Sent by the Nexafon embed page: the origin of the page that frames it (max length 300)
publishableKey	string	yes	pk_live_… or pk_test_…, or a partner’s ppk_live_… or ppk_test_… (min length 1, max length 128)
userToken	string	yes	A JWT (HS256) your server signs with one of the workspace’s secret keys of the same mode: sub (your user id), jti (new for each token) and exp (at most 10 minutes ahead) are required; name, email, email_verified (a boolean) and role are optional. The first time a user signs in, email is required and email_verified must be true: that email links the user to the member with the same email, or to a new member. Later sign-ins use that link and ignore the email. With a partner’s publishable key, the partner’s server signs it with one of the partner’s secret keys (psk_…) of the same mode that has the partner.stores:manage scope, and the session acts with no more than that key’s store permissions: sub (the partner’s user id), name, jti and exp are required, email and locale (en, so or ar) optional, and stores lists 1 to 50 of the partner’s stores as {externalRef, role, teams?}: role is one of owner, admin, supervisor, agent or viewer, and teams, when present, the store’s team ids the user is in. The user becomes or stays an active member of each store with that role (min length 1, max length 32768)

Responses

Status	Description	Body
201	Created	application/json: SDKSessionBody
401	Unauthorized	application/problem+json: Problem
403	Forbidden	application/problem+json: Problem
409	Conflict	application/problem+json: Problem
422	Unprocessable Entity	application/problem+json: Problem
500	Internal Server Error	application/problem+json: Problem

Example

curl -X POST "https://api.nexafone.so/api/v1/sdk/sessions" \
  -H "Content-Type: application/json" \
  -d '{"publishableKey":"string","userToken":"string"}'

Refresh an SDK session

POST /api/v1/sdk/sessions/refresh

Returns a new token; the one sent stops working at once.

Operation id	refreshSdkSession
Authentication	None: the request body carries what the operation needs.

Request body

application/json: TokenInputBody

Field	Type	Required	Description
token	string	yes	The current session token (min length 1, max length 128)

Responses

Status	Description	Body
200	OK	application/json: SDKSessionBody
401	Unauthorized	application/problem+json: Problem
422	Unprocessable Entity	application/problem+json: Problem
500	Internal Server Error	application/problem+json: Problem

Example

curl -X POST "https://api.nexafone.so/api/v1/sdk/sessions/refresh" \
  -H "Content-Type: application/json" \
  -d '{"token":"string"}'

End an SDK session

POST /api/v1/sdk/sessions/revoke

Its realtime connections close.

Operation id	revokeSdkSession
Authentication	None: the request body carries what the operation needs.

Request body

application/json: TokenInputBody

Field	Type	Required	Description
token	string	yes	The current session token (min length 1, max length 128)

Responses

Status	Description	Body
204	No Content
default	Error	application/problem+json: Problem

Example

curl -X POST "https://api.nexafone.so/api/v1/sdk/sessions/revoke" \
  -H "Content-Type: application/json" \
  -d '{"token":"string"}'