Skip to main content
POST
/
v1
/
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"
    }
  }'

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

Documentation Index

Fetch the complete documentation index at: https://docs.affonso.io/llms.txt

Use this file to discover all available pages before exploring further.

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

​
programId
string
required
The affiliate program ID. Must be an active program belonging to your team.
​
partner
object
required
Partner/affiliate information.
​
groupId
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.
​
externalUserId
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.
​
metadata
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

​
success
boolean
Always true for successful responses.
​
data
object
The embed token data.

​
Behavior

  1. User Lookup/Creation: If no user exists with the provided email, a new user is created.
  2. Affiliate Lookup/Creation: If no affiliate exists for this user and program, one is created.
  3. Group Assignment: New affiliates are assigned to the specified groupId or the program’s default group.
  4. 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)
  5. Tracking ID: A unique tracking ID is generated from the name or email.
  6. 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"
    }
  }'

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

​
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.