Skip to main content
Integrate a fully functional referral dashboard into your product. Your users see their stats, referral links, and earnings - all within your app’s interface.

​
Overview

The embedded dashboard displays:
  • Referral link with copy functionality
  • Performance metrics (clicks, leads, sales)
  • Commission earnings and payout status
  • Coupon codes (with optional self-service creation)
  • Marketing resources and creatives

​
Integration Flow

1

Your Server calls Affonso API

POST /v1/embed/token with user data (email, name, image)
2

Affonso returns token

Response includes publicToken, expiresAt, and affiliate link
3

Frontend renders iframe

Embed the dashboard using the token in the iframe URL

​
Step 1: Generate Token

Create an API route on your server that generates a token. This keeps your API key secure.

​
Body Parameters

​
programId
string
required
Your affiliate program ID.
​
partner
object
required
Information about the user you want to display the dashboard for.
​
groupId
string
Affiliate group ID to assign the user to. If not specified, the user is assigned to your program’s default group. Use this to place users in specific commission tiers. Find your group IDs in Dashboard → Affiliate Program → Groups.

​
Example Request

curl -X POST "https://api.affonso.io/v1/embed/token" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "programId": "cm12x98yz0005bnp8h9ld2ff9",
    "partner": {
      "email": "[email protected]",
      "name": "Jane Smith",
      "image": "https://example.com/avatar.jpg"
    },
    "groupId": "e3e6e1b2-5a12-434f-a1b2-4bb0f12c3a89"
  }'

​
Response

{
  "success": true,
  "data": {
    "publicToken": "emb_abc123def456...",
    "expiresAt": "2024-01-15T10:30:00Z",
    "link": "https://yoursite.com?via=jane-smith"
  }
}
New users are automatically registered as affiliates and approved for your program.

​
Step 2: Render the Dashboard

Use the publicToken in an iframe to display the dashboard. 
<iframe
  src="https://affonso.io/embed/referrals?token=emb_abc123def456..."
  className="w-full h-screen border-0"
  allow="clipboard-write"
/>

​
Next.js Example

​
1. Create API Route

First, create a server-side API route that generates the token: 
// app/api/embed-token/route.ts
import { NextResponse } from 'next/server';
import { getServerSession } from 'next-auth';

export async function POST() {
  const session = await getServerSession();

  if (!session?.user) {
    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
  }

  const response = await fetch('https://api.affonso.io/v1/embed/token', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.AFFONSO_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      programId: process.env.AFFONSO_PROGRAM_ID,
      partner: {
        email: session.user.email,
        name: session.user.name,
        image: session.user.image,
      },
    }),
  });

  const data = await response.json();
  return NextResponse.json(data);
}

​
2. Create the Page Component

Then, fetch the token from your API route and render the iframe: 
// app/referrals/page.tsx
'use client';

import { useEffect, useState } from 'react';

export default function ReferralsPage() {
  const [token, setToken] = useState<string | null>(null);
  const [loading, setLoading] = useState(true);

  useEffect(() => {
    async function fetchToken() {
      const res = await fetch('/api/embed-token', { method: 'POST' });
      const { data } = await res.json();
      setToken(data.publicToken);
      setLoading(false);
    }
    fetchToken();
  }, []);

  if (loading) {
    return <div>Loading...</div>;
  }

  return (
    <iframe
      src={`https://affonso.io/embed/referrals?token=${token}`}
      className="w-full h-screen border-0"
      allow="clipboard-write"
    />
  );
}

​
Token Lifecycle

PropertyDetails
Validity30 minutes
RefreshGenerate new token on each page load
CleanupOld tokens are automatically invalidated
Always generate tokens server-side. Never expose your API key to the client.

​
Customization

​
URL Parameters

Add these parameters to the iframe URL for customization:
ParameterValuesDescription
themelight, dark, systemColor scheme. Default: light
bgHEX color (without #)Background color. Use this to match your app’s background. Example: 0f0f0f for dark, ffffff for white
langLanguage codeUI language. Default: en. See supported languages below

​
Supported Languages

The dashboard supports 14 languages:
CodeLanguage
enEnglish (default)
deDeutsch
frFrançais
esEspañol
itItaliano
ptPortuguês
nlNederlands
plPolski
trTürkçe
ja日本語
zh中文
ko한국어
ruРусский
arالعربية
If an invalid language code is provided, the dashboard falls back to English. Example with dark mode, custom background, and German: 
<iframe
  src="https://affonso.io/embed/referrals?token=emb_...&theme=dark&bg=0f0f0f&lang=de"
  ...
/>
Example with light mode and Japanese: 
<iframe
  src="https://affonso.io/embed/referrals?token=emb_...&theme=light&lang=ja"
  ...
/>

​
Brand Colors

The dashboard inherits your brand colors from Portal Settings:
  • Primary Color - Buttons, links, accents
  • Secondary Color - Highlights, backgrounds
Configure colors in HEX format (e.g., #881337) in your Affonso dashboard under Portal Settings.

​
Visual Preview Editor

Don’t want to write code to test settings? Use the visual editor:
  1. Go to Affiliate Program → Appearance
  2. Click the Embed tab
  3. Customize in real-time:
    • Theme: Light, dark, or system (follows user’s device preference)
    • Language: Select from 14 languages – preview updates instantly
    • Background: Pick a color that matches your app
  4. Click Integration Code to copy the configured code snippets
The preview shows your actual branding (logo, colors) so you know exactly what users will see.
Embed preview editor in Affonso dashboard