Session Token

Embedded apps in the Shoplazza admin authenticate using OAuth and session tokens. This guide is for developing embedded apps.


How session tokens work

A session token, also known as a JSON web token (JWT), lets your app authenticate the requests that it makes between the client side and your app's backend. The session token also contains information about the merchant who's currently using your embedded app.

Authentication flow using a session token

When your embedded app first loads, it's unauthenticated and serves up the frontend code for your app. The app renders a user interface skeleton or loading screen to the user.

After the frontend code has loaded, the app calls a Shoplazza App Bridge action to get the session token. Your app includes the session token in an authorization header when it makes any HTTPS requests to its backend.

14521452

Request flow using a session token

The session token is signed using the shared secret between your app and Shoplazza so that your backend can verify if the request is valid.

14441444

Lifetime of a session token

The lifetime of a session token is one minute. Session tokens must be fetched using Shoplazza App Bridge on each request to ensure that stale tokens aren't used.

Anatomy of a session token

A session token consists of a header, payload, and signature. For an interactive example, refer to JWT.io, where you can experiment with setting different values for each section. Shoplazza recommends that you use a test app's credentials when testing on JWT.io.

Header
The values in the header are constant and never change.

{
  "alg": "HS256",
  "typ": "JWT"
}
  • alg: The algorithm used to encode the JWT.
  • typ: The (type) header parameter used by session token to declare the media type.

Payload

{
  "iss": "<shop-name.myshoplaza.com/admin>",
  "dest": "<shop-name.myshoplaza.com>",
  "aud": "<app client id>",
  "sub": "<user ID>",
  "exp": "<time in seconds>",
  "nbf": "<time in seconds>",
  "iat": "<time in seconds>",
  "jti": "<random UUID>",
  "sid": "<session ID>",
  "locale": "zh-CN",
  "account":"[email protected]"
}
  • iss: The shop's admin domain.
  • dest: The shop's domain.
  • aud: The API key of the receiving app.
  • sub: The user that the session token is intended for.
  • exp: When the session token expires.
  • nbf: When the session token activates.
  • iat: When the session token was issued.
  • jti: A secure random UUID.
  • sid: A unique session ID per user and app.
  • locale: The shop's locale.
  • account: The user login account.

Example payload

{
  "locale": "zh-CN",
  "account": "[email protected]",
  "dest": "test.myshoplaza.com",
  "sid": "MTY0MDIyMzE5MHxRaHMzanN1OF9leGdWQTNYZmdqS2tvcnQ0UXpmVlhrZVlhZlJSSG1URTBnOUY4WFNVdl9BVWVmNHozbkVnYU5yc3NwRG9MZFptSGs9fPCmLb7qbttCuZl79rEcRKho9lRqTLZsvs_OESW0um8I",
  "aud": "825a8255676252ee1053073b2b42528c763fd011972ad2803036aea89882920c",
  "exp": 1640331670,
  "jti": "1cf4b3dd-6ccc-4978-9c5a-ad9cee17d4a7",
  "iat": 1640331610,
  "iss": "https://test.myshoplaza.com/admin",
  "nbf": 1640331610,
  "sub": "dafd283d-1274-4412-b86d-21a68ab1172f"
}