Embed a custom view

Once you’ve created and published a custom view, you can embed it in your own app: Paid renders the dashboard in a sandboxed iframe, and a signed token scopes the data to exactly one of your customers. The customer never logs into Paid, and the underlying queries are filtered to that customer in the database, not in the browser.

This is the recommended, easiest integration: your backend asks Paid for a short-lived token using your API key, and the @paid-ai/embed SDK handles the rest. You never manage a signing secret.

Prerequisites

• A published custom view and its displayId (e.g. view_5oi3qvfaFLK). See create a custom view with Claude.
• A Paid API key, used server-side only.

Step 1: Fetch an embed token from your backend

Your backend calls the Paid embed-token endpoint using your API key and returns the token to your frontend. Never expose your API key to the browser.

The endpoint mints a short-lived signed token scoped to a specific customer:

GET https://api.agentpaid.io/api/v2/experimental/views/{displayId}/embed-token
  ?customerId=<customer-id>
  &ttlSeconds=3600          # optional; defaults to 3600, which is also the maximum

Response:

1
{ "token": "<signed-jwt>", "expiresAt": "2026-07-01T01:00:00Z" }

customerId accepts the customer’s Paid display id (cus_…), external id, or internal UUID.

Option A: use the SDK (recommended)

If Paid publishes an SDK for your stack, use it — the typed method makes the request for you and returns the token and its expiry. Call it from your own authenticated backend route and return token / expiresAt to the frontend.

1
import Paid from "@paid-ai/sdk";
2
3
const paid = new Paid({ apiKey: process.env.PAID_API_KEY });
4
5
const { token, expiresAt } = await paid.customViews.getCustomViewEmbedToken(
6
  VIEW_DISPLAY_ID,
7
  { customerId, ttlSeconds: 3600 },
8
);

Option B: call the REST endpoint directly

If there’s no SDK for your stack, call the endpoint over HTTP from your backend:

1
// Your backend route — the browser calls this, never the Paid API directly
2
app.get("/api/paid-view-token", async (req, res) => {
3
  const customerId = getAuthenticatedCustomerId(req); // from your session
4
5
  const response = await fetch(
6
    `https://api.agentpaid.io/api/v2/experimental/views/${VIEW_DISPLAY_ID}/embed-token` +
7
      `?customerId=${encodeURIComponent(customerId)}&ttlSeconds=3600`,
8
    { headers: { Authorization: `Bearer ${process.env.PAID_API_KEY}` } },
9
  );
10
11
  if (!response.ok) {
12
    return res.status(502).json({ error: "Could not fetch embed token" });
13
  }
14
15
  const { token, expiresAt } = await response.json();
16
  res.json({ token, expiresAt });
17
});

Step 2: Embed with the SDK

Install the embed library:

$
npm install @paid-ai/embed

Pass a getToken callback that fetches a fresh token from your backend. The SDK calls getToken for the initial token and again automatically whenever a token expires — you do not need to manage refresh yourself.

1
import { renderCustomView } from "@paid-ai/embed";
2
3
const handle = renderCustomView({
4
  el: "#custom-view-container", // element or CSS selector to mount into
5
  baseUrl: "https://app.paid.ai", // your Paid app base URL
6
  token: "view_5oi3qvfaFLK", // the view's displayId — NOT the JWT
7
  getToken: async () => {
8
    // Fetch a fresh embed token from your backend on load and on expiry
9
    const res = await fetch("/api/paid-view-token");
10
    const { token } = await res.json();
11
    return token;
12
  },
13
});
14
15
// Later, to tear it down:
16
// handle.destroy();

renderCustomView returns a handle:

How scoping and isolation work

• The customer comes only from the verified token’s sub claim — never from a client parameter. An unknown sub, a missing or invalid token, or a token signed for the wrong resource is rejected.
• The view’s queries run against a per-customer database layer that filters every row to the token’s customer. The author’s SQL contains no customer filter; isolation is enforced in the database.
• The dashboard renders in a sandboxed iframe with no network access of its own. The signed token is never passed into that frame — only the already-scoped data for that one customer.