Create Embed Token

curl -X POST "https://api.affonso.io/v1/embed/token" \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "programId": "cm7xutqbb0001yfkcrnpextmp",
    "partner": {
      "email": "affiliate@example.com",
      "name": "John Doe",
      "image": "https://example.com/avatar.jpg"
    }
  }'

const response = await fetch('https://api.affonso.io/v1/embed/token', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer sk_live_your_api_key',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    programId: 'cm7xutqbb0001yfkcrnpextmp',
    partner: {
      email: 'affiliate@example.com',
      name: 'John Doe',
    },
    externalUserId: 'user_123',
    metadata: {
      plan: 'pro',
    },
  }),
});

const { data } = await response.json();
console.log(data.publicToken);

import requests

response = requests.post(
    'https://api.affonso.io/v1/embed/token',
    headers={
        'Authorization': 'Bearer sk_live_your_api_key',
        'Content-Type': 'application/json',
    },
    json={
        'programId': 'cm7xutqbb0001yfkcrnpextmp',
        'partner': {
            'email': 'affiliate@example.com',
            'name': 'John Doe',
        },
        'externalUserId': 'user_123',
        'metadata': {
            'plan': 'pro',
        },
    }
)

data = response.json()['data']
print(data['publicToken'])

{
  "success": true,
  "data": {
    "publicToken": "a1b2c3d4e5f6789...",
    "expiresAt": "2024-01-15T10:30:00.000Z",
    "link": "https://yourcompany.com?via=john-doe",
    "partnershipStatus": "APPROVED"
  }
}

{
  "success": false,
  "error": {
    "code": "PROGRAM_NOT_FOUND",
    "message": "Program not found or not active"
  }
}

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request data",
    "details": {
      "partner": ["Required"]
    }
  }
}

POST

embed

token

curl -X POST "https://api.affonso.io/v1/embed/token" \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "programId": "cm7xutqbb0001yfkcrnpextmp",
    "partner": {
      "email": "affiliate@example.com",
      "name": "John Doe",
      "image": "https://example.com/avatar.jpg"
    }
  }'

const response = await fetch('https://api.affonso.io/v1/embed/token', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer sk_live_your_api_key',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    programId: 'cm7xutqbb0001yfkcrnpextmp',
    partner: {
      email: 'affiliate@example.com',
      name: 'John Doe',
    },
    externalUserId: 'user_123',
    metadata: {
      plan: 'pro',
    },
  }),
});

const { data } = await response.json();
console.log(data.publicToken);

import requests

response = requests.post(
    'https://api.affonso.io/v1/embed/token',
    headers={
        'Authorization': 'Bearer sk_live_your_api_key',
        'Content-Type': 'application/json',
    },
    json={
        'programId': 'cm7xutqbb0001yfkcrnpextmp',
        'partner': {
            'email': 'affiliate@example.com',
            'name': 'John Doe',
        },
        'externalUserId': 'user_123',
        'metadata': {
            'plan': 'pro',
        },
    }
)

data = response.json()['data']
print(data['publicToken'])

{
  "success": true,
  "data": {
    "publicToken": "a1b2c3d4e5f6789...",
    "expiresAt": "2024-01-15T10:30:00.000Z",
    "link": "https://yourcompany.com?via=john-doe",
    "partnershipStatus": "APPROVED"
  }
}

{
  "success": false,
  "error": {
    "code": "PROGRAM_NOT_FOUND",
    "message": "Program not found or not active"
  }
}

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request data",
    "details": {
      "partner": ["Required"]
    }
  }
}

Generate a token to display an affiliate’s dashboard within your application. The token automatically creates the affiliate account if it doesn’t exist.

Body Parameters

string

required

The affiliate program ID. Must be an active program belonging to your team.

object

required

Partner/affiliate information.

Show Partner Object Properties

string

required

Partner’s email address. Used to identify or create the affiliate account.

string

Partner’s display name. Used when creating a new affiliate.

string

Partner’s avatar URL. Must be a valid URL.

string

Optional affiliate group ID. If not provided, uses the program’s default group. Use this to assign new affiliates to specific commission tiers or groups.

string

Your external user ID for linking referral users to your own user system. Useful for matching affiliates back to users in your application. Maximum 255 characters. If provided and the affiliate already exists, this will update their external user ID.

object

Custom key-value data for storing additional information about the affiliate (e.g., {"plan": "pro", "signup_source": "app"}). If provided and the affiliate already exists, this will update their metadata.

Response

boolean

Always true for successful responses.

object

The embed token data.

Show Data Object Properties

string

The token to use for embed data requests. Valid for 30 minutes.

string

ISO 8601 timestamp when the token expires.

string

The affiliate’s full referral link.

string

The affiliate’s partnership status with the program. Either APPROVED or PENDING.

APPROVED: Affiliate can immediately start referring
PENDING: Affiliate needs manual approval before they can earn commissions

This depends on your program’s Access Mode setting (Public vs Private).

Behavior

User Lookup/Creation: If no user exists with the provided email, a new user is created.
Affiliate Lookup/Creation: If no affiliate exists for this user and program, one is created.
Group Assignment: New affiliates are assigned to the specified groupId or the program’s default group.
Partnership: New affiliates are enrolled in the program with a status based on your program’s Access Mode setting:
- Public → Partnership status is APPROVED (affiliate can start referring immediately)
- Private → Partnership status is PENDING (requires manual approval in dashboard)
- Invite → Partnership status is APPROVED (but only pre-invited affiliates can join)
Tracking ID: A unique tracking ID is generated from the name or email.
Token Cleanup: Previous tokens for this affiliate/program are deleted.

curl -X POST "https://api.affonso.io/v1/embed/token" \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "programId": "cm7xutqbb0001yfkcrnpextmp",
    "partner": {
      "email": "affiliate@example.com",
      "name": "John Doe",
      "image": "https://example.com/avatar.jpg"
    }
  }'

const response = await fetch('https://api.affonso.io/v1/embed/token', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer sk_live_your_api_key',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    programId: 'cm7xutqbb0001yfkcrnpextmp',
    partner: {
      email: 'affiliate@example.com',
      name: 'John Doe',
    },
    externalUserId: 'user_123',
    metadata: {
      plan: 'pro',
    },
  }),
});

const { data } = await response.json();
console.log(data.publicToken);

import requests

response = requests.post(
    'https://api.affonso.io/v1/embed/token',
    headers={
        'Authorization': 'Bearer sk_live_your_api_key',
        'Content-Type': 'application/json',
    },
    json={
        'programId': 'cm7xutqbb0001yfkcrnpextmp',
        'partner': {
            'email': 'affiliate@example.com',
            'name': 'John Doe',
        },
        'externalUserId': 'user_123',
        'metadata': {
            'plan': 'pro',
        },
    }
)

data = response.json()['data']
print(data['publicToken'])

{
  "success": true,
  "data": {
    "publicToken": "a1b2c3d4e5f6789...",
    "expiresAt": "2024-01-15T10:30:00.000Z",
    "link": "https://yourcompany.com?via=john-doe",
    "partnershipStatus": "APPROVED"
  }
}

{
  "success": false,
  "error": {
    "code": "PROGRAM_NOT_FOUND",
    "message": "Program not found or not active"
  }
}

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request data",
    "details": {
      "partner": ["Required"]
    }
  }
}

With Custom Group

Assign new affiliates to a specific group with different commission rates:

curl -X POST "https://api.affonso.io/v1/embed/token" \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "programId": "cm7xutqbb0001yfkcrnpextmp",
    "partner": {
      "email": "vip@example.com",
      "name": "VIP Partner"
    },
    "groupId": "cm8abc123vip_group_id"
  }'

Tokens expire after 30 minutes. Generate a new token on each page load rather than caching tokens.

Getting Started

Guide

Core Resources

Program Management

Marketplace

Body Parameters

Response

Behavior

With Custom Group

​Body Parameters

​Response

​Behavior

​With Custom Group

Body Parameters

Response

Behavior

With Custom Group