Create a portal session

Creates a pre-authenticated partner portal URL for a visitor email. This is the foundation of the embedded portal experience — show Introw directly inside your own product with one login and full branding.

How to embed:

Allow-list the domains that may embed Introw under Settings → Developers → Embed (only these domains can load the portal in an <iframe>).
From your backend, call this endpoint with the visitor’s email and your secret API key (portal-sessions:write scope). Keep the key server-side — never call this from the browser.
Drop the returned url into an <iframe>. The URL carries a short-lived sign-in token, so the partner is logged in automatically with no login screen.

The visitor must already have portal access in the organisation resolved from the API key; otherwise the request returns 401. Pass roomId to deep-link the visitor into a specific room (collaboration space) after authentication. Each URL is single-use and short-lived — generate a fresh one per visitor session.

POST

api

auth

session

Create a portal session

curl --request POST \
  --url https://api.introw.io/api/v1/auth/session \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "email": "[email protected]"
}
'

{
  "url": "https://partners.acme.example/rooms/room_01HVK6Y8Z8Q7J8J8J8J8J8J8J8?token=eyJhbGciOiJIUzI1NiJ9.example"
}

Authorizations

x-api-key

string

header

required

Introw API key shown once when the credential is created.

Body

application/json

string<email>

required

Email address of the partner portal visitor. Must already be authorized for the portal in the API key's organisation; otherwise the request returns 401.

Pattern: ^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$

roomId

string | null

Optional room (collaboration space) id to deep-link into after authentication. When omitted, the visitor lands on the portal home.

Minimum string length: 1

Response

Portal session URL created successfully.

url

string<uri>

required

Pre-authenticated, single-use partner portal URL. Embed it directly in an iframe (the embedding domain must be allow-listed under Settings → Developers → Embed). The URL contains a short-lived token, so treat it as a secret and generate a fresh one per visitor session.

Detach a commission line

Record an affiliate conversion

Create a portal session

curl --request POST \
  --url https://api.introw.io/api/v1/auth/session \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "email": "[email protected]"
}
'

{
  "url": "https://partners.acme.example/rooms/room_01HVK6Y8Z8Q7J8J8J8J8J8J8J8?token=eyJhbGciOiJIUzI1NiJ9.example"
}