White-label embed

The embed feature lets a brand drop an iframe into their own product, hosting each affiliate's earnings dashboard at a brand-owned URL. Gated to Growth and higher.

What it does

An affiliate logs into your product as usual. You render an iframe pointing to Rekomi's embed endpoint with a per-affiliate token. The iframe shows the affiliate's earnings, conversions, and payouts for programs they are in. The affiliate never has to leave your domain or log in to Rekomi separately.

Read-only. The embed shows data; it does not let the affiliate take actions (no apply, no profile edit, no tax form upload). For those actions they still go to rekomi.com/a.

Generate a token

POST /api/v1/embed/tokens
Authorization: Bearer rk_live_xxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json

{
  "affiliateId": "01HAFF789...",
  "allowedOrigins": "https://yourapp.com,https://app.yourapp.com",
  "rotate": false,
  "expiresInHours": 24
}

Required:

• affiliateId: the affiliate to scope this token to. Must be an affiliate in one of your programs.
• allowedOrigins: comma-separated list of origins (scheme + host + port) that can frame the embed. Strict equality match; no wildcards. Empty list = the public dashboard endpoint returns 403 no_allowed_origins_configured.

Optional:

• rotate (boolean, default false): when true, replaces any existing token for the (program, affiliate) pair with a fresh one. When false and a token already exists, the response returns the existing token's metadata (id, allowed origins, expires) with alreadyExists: true and no plaintext token; you must rotate: true to mint a new plaintext.
• expiresInHours (integer, default 24, clamped to [1, 720]): time-to-live in hours. Beyond 30 days (720 hours), rotate rather than extend.

Response (new or rotated token):

{
  "token": "embed_01HV...",
  "allowedOrigins": "https://yourapp.com,https://app.yourapp.com",
  "expiresAt": "2026-05-12T03:14:25.000Z"
}

The plaintext token is returned EXACTLY ONCE. Store it in your application server before passing to the browser; we cannot recover it. Hash-at-rest on our side; lookup on the public dashboard endpoint hashes the inbound token before compare.

Tokens default to 24 hours. Generate fresh tokens when the affiliate signs in. Do not pass long-lived tokens to the browser.

Render the iframe

<iframe
  src="https://api.rekomi.com/api/embed/public/dashboard?token=embed_01HV..."
  style="width: 100%; height: 600px; border: 0;"
></iframe>

The iframe page renders read-only earnings and conversions for the affiliate the token was issued to. Styled to inherit accent color from the brand (see Customization below).

Origin allowlist

The embed enforces a strict origin check. The Origin header sent by the browser (when the iframe loads) must exactly equal one of the entries in allowedOrigins. Comparison is:

• Scheme (https vs http)
• Host
• Port (explicit if non-default)

No StartsWith checks. No subdomain wildcards. Required because a StartsWith rule would allow https://yourapp.com.evil.example.com to bypass.

If you need multiple origins, add them all to the list. If you serve from many subdomains, generate per-deploy tokens that include only the relevant origin.

What the embed shows

The GET /api/embed/public/dashboard?token=... endpoint returns:

Realistic JSON response:

{
  "affiliateName": "Jane Doe",
  "programName": "Default program",
  "earnedCents": 12450,
  "paidCents": 9800,
  "pendingCents": 2650,
  "brandColor": "#0E7C7B",
  "brandName": "Your Brand",
  "recentConversions": [
    {
      "id": "c0nv0001-...",
      "amountCents": 9900,
      "commissionCents": 1980,
      "status": "Approved",
      "createdAt": "2026-05-10T16:00:00Z"
    }
  ]
}

That is the full payload. No tax forms, no Stripe Connect status, no settings, no IPs, no PII beyond what the affiliate has consented to display.

What the embed does NOT show

• Other organizations' programs (even if the affiliate is in multiple)
• Tax form status (PII)
• Stripe Connect bank details (PII)
• Other affiliates' data

The embed is strictly scoped to one (organization, affiliate) pair.

Customization

The Dashboard response surfaces brandColor (from your organization's PrimaryBrandColor setting at /dashboard/settings/branding, defaulting to #0E7C7B when unset) and brandName (your org's display name). Render the iframe shell on your side using those values to match your product's look.

Text color, layout, and typography are not server-customizable yet; the embed body returns data only. Future releases will add a customization JSON (hide/show columns, header text, custom CSS variables) on the token creation request.

Plan gate

POST /api/v1/embed/tokens is gated to Growth plan and higher via [RequiresPlan(PlanTier.Growth)]. If your org is on Starter, the endpoint returns HTTP 402 with { error: "plan_tier_required", required: "Growth", current: "Starter" }.

Security checklist

• Always generate tokens server-side. Never expose the bearer API key to the browser.
• Always set allowedOrigins to the exact production origin.
• Generate fresh tokens per session (do not reuse a 24-hour token across many sessions).
• Verify the Authorization of your incoming user request before minting a token (only the actual logged-in affiliate should get a token for their own data).
• Use a Content Security Policy that restricts which iframes can load on your site.

Troubleshooting

• Iframe shows "origin not allowed": your Origin header does not match anything in allowedOrigins. Check scheme, host, port for exact equality.
• Iframe shows "origin_required": the browser did not send an Origin header (e.g., curl, server-to-server). The embed dashboard endpoint requires Origin even when allowedOrigins is set.
• Iframe shows "token_expired": token's expiresAt is in the past. Generate fresh on next session.
• Iframe shows "affiliate not found": the affiliate is not in your organization. The token's affiliateId must reference an affiliate you own.
• Iframe is blank: check your browser console. Most likely a Content Security Policy on your side is blocking the iframe. Add frame-src https://api.rekomi.com to your CSP.