Create Embed Token

Generate a short-lived public token for rendering the embedded referral portal for a specific partner.

POST /api/embed/token

Generates a short-lived public token that authorises a specific partner to view the embedded referral portal. The token is safe to expose to the browser — it's scoped to a single partner and expires quickly.

Request

Headers

Header	Value
`Authorization`	`Bearer YOUR_API_KEY`
`Content-Type`	`application/json`

Body

{
  "partner": {
    "email": "alice@example.com",
    "name": "Alice"
  },
  "tenantId": "org_001"
}

At least one of tenantId, enrollmentId, or partner must be provided.

Field	Type	Required	Description
`partner.email`	`string`	Yes (if partner provided)	Partner's email address — used to look up or create the partner
`partner.name`	`string`	No	Partner's display name — used when creating a new partner
`tenantId`	`string`	No	Your internal organisation or tenant ID
`enrollmentId`	`string`	No	Bind the token to an existing enrollment record

If the partner does not exist in the program yet, Refport creates them automatically using the provided email and name.

Response

200 OK

{
  "publicToken": "pt_abc123...",
  "expires": "2024-01-15T12:30:00.000Z"
}

Field	Type	Description
`publicToken`	`string`	The token to pass to `<RefportEmbed>` or use in the iframe URL
`expires`	`string`	ISO 8601 timestamp indicating when the token expires

Error responses

Status	Code	Description
`401`	`UNAUTHORIZED`	Invalid or missing API key
`404`	`NOT_FOUND`	No active referral program found for the organization
`422`	`VALIDATION_ERROR`	Missing or malformed required field
`429`	`RATE_LIMIT_EXCEEDED`	Too many requests — retry after backing off

Token lifetime

Tokens expire after a short period (see the expires field in the response). Generate a fresh token on each page load — do not cache tokens across sessions or users.

SDK equivalent

const token = await refport.embedTokens.create({
  tenantId: 'org_001',
  partner: {
    email: 'alice@example.com',
    name: 'Alice',
  },
});
// token.publicToken — pass to <RefportEmbed>
// token.expires — Date object

See the Node.js SDK reference and Embedded Portal guide for full usage.