Skip to content
Dashboard
Theme
Theme

Portal links

How to create a portal link with POST /v1/portal/links or invite an IT contact from the dashboard, how long links and sessions last, and how to revoke them.

View Markdown

Create a link on your server using POST /v1/portal/links, authenticated with a secret key scoped for portal_links:write. Supply the organization and allowed intents. Resolve the organization from your application’s authorized customer context, not an untrusted request parameter.

The link response returns its URL once. The URL carries a token in its fragment (#token=…); treat the entire URL as a credential. When the environment has a verified custom portal hostname, the URL uses it (the first one verified, if there are several); otherwise it uses the default portal origin. The session cookie stays host-only on whichever origin serves the page. Do not log it, put it in analytics or expose it to unrelated customers. A setup link lasts 7 days by default. Set expires_in to choose its lifetime, from 300 seconds (5 minutes) to 2,592,000 seconds (30 days); the default is the same for links made through the API and in the dashboard. A setup link an API key creates opens once; one a member creates in the dashboard can be opened again until it ends. Both can be revoked, and expires_at in the response says when the link ends. For a sealed single-use embed link, send ttl (60 to 300 seconds) instead. Sending both, or a value outside its range, answers parameter_invalid. Invites are a separate workflow with their own lifetimes.

Opening the link starts a portal session. Redemption is single-use, and the portal protects every change the IT admin makes against cross-site requests.

The __Host-ohc_portal_session cookie is Secure, HttpOnly, SameSite=Strict and host-only, with a one-hour absolute lifetime and 30-minute idle limit. Revoking a link ends its sessions. Do not reuse the management secret in a browser or build your own long-lived cookie from the link token.

GET /v1/portal/links does not return the secret URL. Revoke a link with POST /v1/portal/links/{link}/revoke. Supply only approved return and success destinations; treat them as part of your application’s redirect policy.

The portal is available in English and in machine-translated German (de), Spanish (es), French (fr), Japanese (ja) and Brazilian Portuguese (pt-BR). Set the optional locale on a link or an invite to choose the language the portal starts in. Without it, the portal uses the browser’s language when it is one of these, and English otherwise. Any other value answers 400 parameter_invalid with param set to locale.

The IT admin can switch language at any time, and can view any translated message in English. Identity provider console labels and placeholders stay in English. The redeemed portal context reports the starting locale, or omits it when you set none. The set of languages may grow within v1, so treat an unknown value as English.

See the management reference.

Business and Enterprise links can reference a portal profile to restrict providers and features and require configured attribute mappings. The server enforces the current profile on unfinished setup actions. Completion is an explicit, audited Finish step in the portal for that link; a return redirect does not complete setup. Finished links accept no more edits. Links without a profile retain their existing behavior.

For an already redeemed link without a profile, the original redemption-link expiry does not shorten its authenticated session lifetime. Session expiry, revocation, organization scope and any connection pin still apply. Profile-backed links retain their additional expiry and completion guards.