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.
Header
| 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 − iatmay 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
ordersandaddress-form: a customer token (withoutord).order: an order-scoped token withordset 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);<?php
// Server side only. $shop: "<name>.myshopify.com"; $customerId / $orderId: numeric Shopify ids.
function mintAvioToken(string $secret, string $shop, string|int $customerId, string|int|null $orderId = null, int $ttlSeconds = 600): string
{
$b64 = fn (array $value): string => rtrim(strtr(base64_encode(json_encode($value, JSON_UNESCAPED_SLASHES)), '+/', '-_'), '=');
$iat = time();
$claims = ['shop' => $shop, 'sub' => "gid://shopify/Customer/{$customerId}", 'iat' => $iat, 'exp' => $iat + $ttlSeconds];
if ($orderId !== null) {
$claims['ord'] = "gid://shopify/Order/{$orderId}";
}
$header = ['alg' => 'HS256', 'typ' => 'JWT', 'kid' => explode('_', $secret)[1]];
$unsigned = $b64($header) . '.' . $b64($claims);
$signature = rtrim(strtr(base64_encode(hash_hmac('sha256', $unsigned, $secret, true)), '+/', '-_'), '=');
return "{$unsigned}.{$signature}";
}
$secret = getenv('AVIO_WIDGET_SECRET');
$token = mintAvioToken($secret, 'your-store.myshopify.com', $customerId);
$orderToken = mintAvioToken($secret, 'your-store.myshopify.com', $customerId, $orderId);import os
import time
import jwt # PyJWT
# Server side only. shop: "<name>.myshopify.com"; customer_id / order_id: numeric Shopify ids.
def mint_avio_token(secret, shop, customer_id, order_id=None, ttl_seconds=600):
iat = int(time.time())
claims = {
"shop": shop,
"sub": f"gid://shopify/Customer/{customer_id}",
"iat": iat,
"exp": iat + ttl_seconds,
}
if order_id is not None:
claims["ord"] = f"gid://shopify/Order/{order_id}"
return jwt.encode(claims, secret, algorithm="HS256", headers={"kid": secret.split("_")[1]})
secret = os.environ["AVIO_WIDGET_SECRET"]
token = mint_avio_token(secret, "your-store.myshopify.com", customer_id)
order_token = mint_avio_token(secret, "your-store.myshopify.com", customer_id, order_id)import base64
import hashlib
import hmac
import json
import os
import time
def _b64(data):
return base64.urlsafe_b64encode(data).rstrip(b"=").decode()
# Server side only. shop: "<name>.myshopify.com"; customer_id / order_id: numeric Shopify ids.
def mint_avio_token(secret, shop, customer_id, order_id=None, ttl_seconds=600):
iat = int(time.time())
claims = {
"shop": shop,
"sub": f"gid://shopify/Customer/{customer_id}",
"iat": iat,
"exp": iat + ttl_seconds,
}
if order_id is not None:
claims["ord"] = f"gid://shopify/Order/{order_id}"
header = {"alg": "HS256", "typ": "JWT", "kid": secret.split("_")[1]}
unsigned = _b64(json.dumps(header).encode()) + "." + _b64(json.dumps(claims).encode())
signature = hmac.new(secret.encode(), unsigned.encode(), hashlib.sha256).digest()
return unsigned + "." + _b64(signature)
secret = os.environ["AVIO_WIDGET_SECRET"]
token = mint_avio_token(secret, "your-store.myshopify.com", customer_id)
order_token = mint_avio_token(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:
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. |