Vai al contenuto
Address Validation iO

Questa documentazione è disponibile solo in inglese.

Widget headless

Widget tokens

Sign a short-lived token on your server so the headless widget can load the signed-in customer's orders.

The headless widget never sees your customer login. Instead, your storefront's server signs a short-lived token for the signed-in customer on every page view and puts it into the page. Address Validation iO checks the signature and only then shows that customer's orders.

The widget secret

You get the secret in the Address Validation iO Shopify app under Settings → Customer accounts & headless → Set up the headless widget → Generate secret. It looks like avw_<keyId>_<64 hex characters> and is shown only once.

  • Store it as an environment variable on your server, for example AVIO_WIDGET_SECRET.
  • Never send it to the browser or commit it to your code.
  • Rotate secret creates a new one. Tokens signed with the old secret stop working at once, so update your server right away.

Token format

The token is a compact JWT signed with HMAC-SHA256 (HS256). Header, claims and signature are base64url-encoded without padding and joined with dots.

The HMAC key is the whole secret string, including the avw_ prefix.

Field Value
alg HS256 (required)
typ JWT
kid The key id: the part of the secret between the first and second _, for example 1a2b3c4d from avw_1a2b3c4d_… (required)

Claims

Claim Type Value
shop string Your shop's <name>.myshopify.com domain
sub string The signed-in customer's GID: gid://shopify/Customer/<id>
ord string, optional An order GID: gid://shopify/Order/<id>. The token then only works for that order.
iat number Issued at, in Unix seconds
exp number Expires at, in Unix seconds

Lifetime

  • Use 600 seconds (10 minutes) by default.
  • exp − iat may be at most 900 seconds (15 minutes); longer tokens are refused.
  • Up to 30 seconds of clock difference between your server and Address Validation iO are tolerated.

Mint a fresh token on every page view. When a token expires, the order widget shows "Your session has expired. Please reload the page."

Which token for which widget

  • orders and address-form: a customer token (without ord).
  • order: an order-scoped token with ord set to the order on that page.

Address Validation iO also checks that the order belongs to the customer in sub.

Mint a token

Each example mints a customer token and an order-scoped token. customerId and orderId are numeric Shopify ids, for example from the Customer Account API.

import { createHmac } from "node:crypto";

// Server side only. shop: "<name>.myshopify.com"; customerId / orderId: numeric Shopify ids.
export function mintAvioToken(
  secret: string,
  shop: string,
  customerId: string | number,
  orderId?: string | number,
  ttlSeconds = 600,
): string {
  const b64 = (value: object) => Buffer.from(JSON.stringify(value)).toString("base64url");
  const iat = Math.floor(Date.now() / 1000);
  const claims: Record<string, string | number> = {
    shop,
    sub: `gid://shopify/Customer/${customerId}`,
    iat,
    exp: iat + ttlSeconds,
  };
  if (orderId !== undefined) claims.ord = `gid://shopify/Order/${orderId}`;
  const header = { alg: "HS256", typ: "JWT", kid: secret.split("_")[1] };
  const unsigned = `${b64(header)}.${b64(claims)}`;
  return `${unsigned}.${createHmac("sha256", secret).update(unsigned).digest("base64url")}`;
}

const secret = process.env.AVIO_WIDGET_SECRET!;
const token = mintAvioToken(secret, "your-store.myshopify.com", customer.id);
const orderToken = mintAvioToken(secret, "your-store.myshopify.com", customer.id, order.id);

Put the token into the page

Render the token into the widget element on the server, for example in a Next.js server component:

Next.js
const token = mintAvioToken(process.env.AVIO_WIDGET_SECRET!, "your-store.myshopify.com", customer.id);

return <div data-avio-widget="orders" data-token={token} data-order-url="/account/orders/{id}" />;

Only render widgets for signed-in customers. Anyone who has a token can read that customer's widget data until it expires, so keep the lifetime short and never cache pages that contain a token for other visitors.

Common errors

Symptom Likely cause
The order widget says "Your session has expired" The API refused the token (HTTP 401): it expired (exp plus 30 seconds), the secret was rotated, or the token is invalid (wrong secret or kid, a shop that doesn't match your store, a lifetime over 900 seconds, iat in the future).
The orders notice shows nothing The same token problems (the notice stays empty on any error), or no order needs attention.
The order widget stays empty The order-scoped token is for another order, the order isn't this customer's, or Address Validation iO never checked the order.