​
Introduction

Embedding a store or product pages inside your app doesn’t require authentication using private safe sessions. You can serve public stores that are open to anonymous visitors. This method is used as an easy way for you to securely transfer information between your app and SideDish on the client. The decision on authentication is totally yours. If you don’t need to ensure validity of properties, you could pass all parameters unsafely. Both methods are easy to implement. We recommend authenticating usres, but if you don’t rely on any input from the user, and you manage purchases on your own, you can avoid authentication altogether.

Safe sessions allow you to achieve two main things:

  1. Authenticate users on SideDish. SideDish doesn’t create users on its own, but instead relies on the authentication of your app. This means that users don’t need to go through another login flow.
  2. Pass parameters from your app to SideDish safely.

In order to do this, you can call a REST api request or use the prebuilt @sidedish/core package with its createSession function.

​
Creating a session

Creatign safe sessions should be done on the server side, and never on the client side. Make sure you never pass your secret API key or personal tokens to the client!

storeId
string

Store you want to use.

userId
string
required

Any unique identifier of a user. We suggest you use your existing userId (may it be a uuid or an email). It is required because there is no point in creating a session without passing a user.

data
AcceptableParameters

Object with any extra parameters you want to pass to SideDish.

​
Response

sessionId
string

The id of the safe session

expiresAt
string

The expiresAt of the session in ISO string

​
Acceptable parameters

​
User data and user’s account

All but userId are optional.

userId
string
required

Pass this as your user id to be act upon.

userName
string

Pass this to see user’s name in the dashboard, logs and analytics.

user
json

Anything you want to send for the user’s properties.

Please note that if you pass internal property in the user object, it will disable tracking and analytics for the user.

accountId
string

id for the logged in user’s account. This is especially useful if your app is a B2B and you want to support account level features.

accountName
string

Pass this to see account’s name in the dashboard, logs and analytics.

account
json

Anything you want to send for the account’s properties.

​
Purchases

If you are managing the purchases of products yourself, you can pass what are the products the user / account has installed.

purchases
string[] | Purchase[]

Array of id strings or Objects that include id and data for the installation

Purchase Type:

​
Updating a session with new data

If you are managing the installation state and you want to update a session you could send new data with:

sessionId
string
required

The id of the session

data
AcceptableParameters
required

Updated data

Updating a userId isn’t possible and you should just create a new session.

​
Revoking a session

Even though sessions are relatively short lived, you can still choose to revoke a session. This is useful if you want to log out a user.

sessionId
string
required

The id of the session

Related productsEmbeddables