Create hosted sessions

The four POST /session/* endpoints mint stateless, unauthenticated Talentir URLs you send your users to — no iframe or UI work on your side. The endpoint validates the resource for the authenticated team (with OAuth this can be a customer's team that connected your app) and returns a url.

Sessions are stateless: nothing is stored. Treat the returned url as opaque — redirect the user to it as-is; do not build, parse, or depend on its shape. The URL itself confers no standing access — every screen still authenticates the visitor and gates the action — so a link is safe to email or hand to its intended recipient.

Two audiences — send each link to the right person

Endpoint	Audience	Purpose
`/session/payout`	The payout recipient (a creator, not a team member)	Sign up / sign in and claim a payout
`/session/approval`	A member of the authenticated team	Review and approve pending payouts
`/session/kyb`	A team member	Complete business verification
`/session/allowance`	The team owner	Set the daily spending allowance

Team links (/session/approval, /session/kyb, /session/allowance) are for members of the team the token authorizes. The screen requires the visitor to sign in and be a member of that team — anyone else gets a "request access" prompt. The sign-in code is pre-sent to the session creator; the optional loginHint field overrides who receives it.

The recipient link (/session/payout) is for the person being paid, who is not a member of your team. The screen shows the payout and lets the recipient sign in or sign up with their own email and claim it; no team membership is required.

Do not send a team link to a recipient or vice versa.

Non-members can request access

It is safe to send a team-scoped session link to someone who is not (yet) a member of the team: after signing in they see a "Request access" screen instead of the flow. Requesting access emails the team's owner(s) with the requester's name and email and a one-click link to invite them from team settings — access is never granted automatically. Once invited and accepted, the same session link works.

Wallet setup

The team-member flows all operate on the team's wallet — a passkey wallet held by the team owner. If the team has not set one up yet, the hosted screen first prompts the owner to create it and then continues to the requested flow. Only the owner can complete this step; a non-owner member is asked to have the owner do it. A team must finish wallet setup before its payouts can be approved or executed. The recipient claim flow is unaffected — it uses the recipient's own wallet.

Common parameters

Parameter	Required	Effect
`redirectUrl`	yes	Where the user is returned after completing or leaving the screen — also the target of the screen's "Go Back" control. Must be http/https.
`branding`	no	`talentir` (default), `team`, or `platform`. Selects the host and logo for the hosted flow.

Each endpoint adds its own input — payoutId (payout), payoutIds (approval), and optional loginHint values for the team-member flows. All require the sessions:write scope, which is granted by default.

White-label branding

`branding`	Hosted on	Requires
`talentir` (default)	The main Talentir host	—
`team`	The authenticated team's white-label subdomain (`{slug}.talentir.com`) with its logo	The team's white-label feature + configured subdomain
`platform`	The subdomain and logo of the team operating your OAuth client	An OAuth-authenticated call with a dashboard-created client, and the operating team's white-label feature

platform is the mode for platforms embedding Talentir-hosted flows in their own product: the session operates on the connected customer team, while the page chrome carries your brand. It is rejected for API-key calls (an API key has no operating platform). The deprecated whitelabel field on /session/payout is ignored — use branding: "team" instead. White-label features and subdomains are provisioned by Talentir as part of the partner program.

Sandbox and preview hosts do not provide per-team subdomains. On these hosts, Talentir keeps the session on the current host and carries the verified brand in a signed session token.

Examples

Team link — a member of the authenticated team approves payouts:

curl -X POST "$BASE_URL/session/approval" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "branding": "platform",
    "payoutIds": ["0e4ba886-0bfe-4b6a-ae2e-d6d9d135dd1e"],
    "redirectUrl": "https://yourapp.com/done"
  }'

Recipient link — the creator being paid claims their payout:

curl -X POST "$BASE_URL/session/payout" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "payoutId": "0e4ba886-0bfe-4b6a-ae2e-d6d9d135dd1e",
    "redirectUrl": "https://yourapp.com/done"
  }'