ShipStream Knowledge Base
Integrations

Custom Embedded Dashboard

Replace the built-in merchant dashboard with one you build and host yourself. ShipStream shows your page in a frame on the Client Portal Dashboard and on Dashboard -> Client Dashboard in the Admin UI. Each time it loads the frame, ShipStream signs a short-lived JSON Web Token (JWT) that says which Merchant, and in the Admin UI which Warehouses, the viewer may see. Your dashboard verifies the token with a secret key it shares with ShipStream, then loads its figures from the ShipStream API.

The same setup can also replace the Admin UI Dashboard with a warehouse view of your own. See Warehouse Hub.

Who can set it up

Admin UI users whose role includes the System -> Configuration -> Client Dashboard permission can change these settings. No role gets it automatically. Grant it under System > Users > User Roles. See User Roles.

The URL, Secret Key and timing settings apply to every Merchant. Only Enabled can be set per Merchant.

How it works

  1. A user opens the dashboard. ShipStream signs a token for that user's Merchant and Warehouses, and loads your URL in a frame with the token after #token=.
  2. Your page reads the token from the address and sends it to your server with each request.
  3. Your server verifies the token with the Secret Key, then calls the ShipStream API with its own credentials, limited to the Merchant and Warehouses named in the token.
  4. Every Auto-Refresh Period while the page is visible, ShipStream replaces the token with a new one.

The token is placed after #, so browsers never send it to your server in the page request, and it is left out of Referer headers.

Set up the dashboard

  1. Host your dashboard on HTTPS. Browsers refuse to show an http:// page inside ShipStream.
  2. Allow ShipStream to show it in a frame by sending Content-Security-Policy: frame-ancestors https://<your ShipStream address>, and no X-Frame-Options header.
  3. Generate a random secret of at least 32 bytes, for example with openssl rand -base64 48, and give it to your dashboard's server.
  4. In ShipStream, open System -> Configuration -> Clients -> Dashboard with Current Configuration Scope set to Global, and fill in Custom Embedded Dashboard (beta):
    FieldWhat to enter
    Secret KeyThe secret from step 3.
    URLYour dashboard's address, such as https://dash.example.com/view. Query parameters in it are kept.
    JWT ExpirationHow many seconds each token is valid. Default 300. Make it longer than the Auto-Refresh Period, such as 600, so a token is still valid when the next one arrives.
    Auto-Refresh PeriodHow often ShipStream sends a new token while the page is visible, in seconds. Default 300, from 60 to 86400.
    Use for Admin DashboardLeave at No unless your dashboard serves the Warehouse Hub.
  5. Set Enabled to Yes. At Global scope this turns the embedded dashboard on for every Merchant. To try it with one Merchant first, leave it at No here, choose that Merchant under Current Configuration Scope, and set Enabled to Yes there.
  6. Click Save Config, then open Dashboard -> Client Dashboard and choose the Merchant.

A Merchant without Enabled keeps the built-in dashboard. If the URL or Secret Key is missing, every Merchant keeps the built-in dashboard.

The frame address

ShipStream loads your URL with query parameters added and the token after #:

PageAddress
Client Portal Dashboardhttps://dash.example.com/view?website_hash=…#token=…
Admin UI Dashboard -> Client Dashboardhttps://dash.example.com/view?website_hash=…&warehouse_hash=…#token=…
Admin UI Dashboard, with Use for Admin Dashboardhttps://dash.example.com/view/hub/warehouse?scope_hash=…#token=…

The *_hash values change whenever the Merchant or Warehouse selection changes, so the browser loads a fresh page instead of reusing the old one. Do not use them to decide what to show. Read the Merchant and Warehouses from the verified token.

When only the token changes, the browser does not reload your page. It fires a hashchange event, and your page should read the new token then.

The token

The token is signed with HS256 using the Secret Key. A merchant dashboard token holds:

ClaimMeaning
website_idThe Merchant's ID, as a string. It is the merchant_id used by the Global API.
warehouse_idsAdmin UI Client Dashboard only: the Warehouse IDs selected in the page header. Show figures for these Warehouses only. When it is missing, the viewer may see all of the Merchant's Warehouses.
localeThe viewer's locale, such as en_US.
media.product_base_urlPrefix for a Product's thumbnail path, for showing product images.
media.placeholder_urlImage to show when a Product has no thumbnail.
iat, expIssue and expiry times, in seconds since 1970 (UTC).

A Client Portal token never holds warehouse_ids, because a Merchant's users see every Warehouse that serves the Merchant.

On your server:

  • Accept HS256 only, and reject tokens whose signature or exp does not check out. Allow up to a minute of clock difference.
  • Require website_id for a merchant dashboard. A Warehouse Hub token has scope set to admin and no website_id, so the two can never be confused.
  • Limit every API call to merchant_id equal to website_id, and to warehouse_ids when present.
  • Keep your ShipStream API credentials on the server. Never send them to the browser.
  • Treat the token like a password: do not log it or store it.

Example with Node.js and the jose library:

import { jwtVerify } from 'jose';

const secret = new TextEncoder().encode(process.env.SHIPSTREAM_DASHBOARD_SECRET);

// Returns what the viewer may see, or throws when the token is not valid.
export async function readViewer(authorizationHeader) {
  const token = (authorizationHeader || '').replace(/^Bearer /, '');
  const { payload } = await jwtVerify(token, secret, { algorithms: ['HS256'], clockTolerance: 60 });
  if (payload.scope === 'admin') {
    return { hub: true, warehouseIds: payload.warehouse_ids, merchantIds: payload.website_ids };
  }
  if (typeof payload.website_id !== 'string') {
    throw new Error('Not a dashboard token');
  }
  return { hub: false, merchantId: Number(payload.website_id), warehouseIds: payload.warehouse_ids ?? null };
}

Talking to ShipStream from the page

Browsers often block cookies inside a frame from another site, so keep the token in memory and send it to your server in an Authorization: Bearer header. Remove it from the address once read:

const SHIPSTREAM_ORIGIN = 'https://example.shipstream.app'; // your ShipStream address
let token = null;

function takeToken() {
  const next = new URLSearchParams(location.hash.slice(1)).get('token');
  if (next) {
    token = next;
    history.replaceState(null, '', location.pathname + location.search);
  }
}

takeToken();
window.addEventListener('hashchange', () => {
  takeToken();
  loadFigures(); // fetch your data again with the new token
});

The page and ShipStream exchange messages with postMessage. ShipStream accepts messages only from the origin of the configured URL and sends messages only to it. Check event.origin against your ShipStream address on your side as well.

Message from your pageWhat ShipStream does
{ type: 'resize', height: 1240 }Sets the frame's height in pixels, from 1 to 20000. Send it whenever your content's height changes. Until the first one arrives, the frame fills the rest of the window.
{ type: 'iframe-ready' }Replies with the address of the ShipStream page as a string. ShipStream also sends it each time the frame loads.
{ type: 'navigate', route: 'sales_order/view', params: { order_id: '1234' } }Opens that ShipStream page in place of the dashboard. See below.
function send(message) {
  window.parent.postMessage(message, SHIPSTREAM_ORIGIN);
}

new ResizeObserver(() => {
  send({ type: 'resize', height: document.documentElement.scrollHeight });
}).observe(document.documentElement);

The frame cannot open new windows or navigate ShipStream itself. Use navigate for links into ShipStream. ShipStream checks the route, its parameters, and that the record belongs to the Merchant, and ignores anything else:

RouteParametersOpens
sales_order/vieworder_id: the Order's id from the Global API, not its order numberThe Order
sales_order_shipment/viewshipment_id: the Shipment's idThe Shipment
catalog_product/editid, or skuThe Product
sales_order/indexNoneThe Orders grid
sales_shipment/indexNoneThe Shipments grid
sales_package/indexNoneThe Packages grid
catalog_product/indexNoneThe Products grid
delivery/indexNoneThe Deliveries grid
work/indexNoneThe Work Orders grid

In the Admin UI, a grid opens for the Merchant and the Warehouses selected in the page header.

Warehouse Hub

With Use for Admin Dashboard set to Yes, the Admin UI Dashboard shows your page instead of the built-in dashboard. ShipStream adds /hub/warehouse to your URL's path, so https://dash.example.com/view becomes https://dash.example.com/view/hub/warehouse. Turn it on only when your dashboard serves that page.

A Warehouse Hub token holds:

ClaimMeaning
scopeAlways admin.
warehouse_idsThe Warehouse IDs selected in the page header that the user may see.
website_idsThe Merchant IDs the user may see, or null when the user may see every Merchant.
admin_user_idThe ID of the Admin UI user, for your own records. Do not use it to decide what to show.
timezoneThe time zone of the selected Warehouse, such as America/New_York, or the default time zone when several are selected. Use it for "today" and other day boundaries.
locale, media, iat, expAs in the merchant dashboard token.

The hub can open the sales_order/index, sales_shipment/index, sales_package/index, catalog_product/index, delivery/index and work/index grids, and also cyclecount/index, putaway/index, relocation/index and replenishment_task/index, all without parameters. It cannot open single records.