# Hosted portal

The setup portal is an organization-scoped workflow for a customer's IT administrator. Its backend supports domain verification, configuring and testing connections, activation and directory setup. This guide describes those implemented interfaces, not a claim that a hosted deployment is available.

Your server creates a short-lived [portal link](/hosted-portal/portal-links/) with only the [intents](/hosted-portal/intents/) needed for that customer. The IT admin configures the IdP; your application consumes profiles and provisioning events.

A connection must pass its test before activation.

<a id="activation-gate"></a>

## Activation needs a verified domain

The setup portal turns single sign-on on only for a tested connection of an organization with at least one verified domain. An untested connection answers [`test_sign_in_pending`](/errors/test_sign_in_pending/) first; with no verified domain, the portal's activate call answers HTTP 409 with the portal state [`domain_unverified`](/errors/domain_unverified/). Include the `domain_verification` intent in the portal link, or verify the domain first, so the IT admin can finish.

Activation through the management API (`POST /v1/connections/{conn}/activate`) does not require a verified domain. Sign-ins with an email outside the organization's verified domains are refused on every path ([`email_outside_verified_domain`](/errors/email_outside_verified_domain/)).

## Boundaries

Portal sessions cannot read another organization's resources. Link redemption and state-changing requests have their own security requirements; a management API key is never a portal browser credential.

Use [test sign-ins and Connection Doctor](/hosted-portal/connection-doctor/) to inspect checks and supported fixes through either the portal or management API. The portal can send fix instructions to a scoped IT contact. A migration-scoped portal session can supply IdP metadata for an imported draft SAML connection that has no metadata yet; submit either its metadata URL or document. Portal links and invites use your verified custom portal hostname when you have one.

Business and Enterprise environments can attach [portal profiles](/hosted-portal/profiles/) to constrain provider choices and required configured attributes. Setup completion is explicit; these backend interfaces do not imply that every control is shipped in a portal frontend.

Use [signing-key rotation](/sso/signing-key-rotation/) for acknowledgement, testing and confirmation, and [customer IT email](/hosted-portal/customer-it-email/) for the environment-scoped messages eligible for customization. Platform authentication and security mail remain platform-controlled.

## Embed the portal in your app

To show the setup portal inside your own app in an iframe, list your app's origins in `portal_embed_origins` with `PATCH /v1/environment` (set per environment with that environment's key; at most 20 bare `https` origins, normalised to lower case without a default port; `[]` turns embedding off). Then show a portal link with the [JavaScript SDK](/sdks/javascript/#admin-portal-embed) or the [React SDK](/sdks/react/)'s `AdminPortal` component.

- While origins are set, the portal session cookie is issued with `SameSite=None; Secure; Partitioned`, so it works in a third-party frame and stays partitioned to your site. Otherwise it stays `SameSite=Strict`. State-changing requests still need the CSRF header.
- The portal reports the allowed origins to its frontend as `embed_origins`.
- OhAuthCat publishes the origins to the edge for the environment and its active custom portal domains: a change reaches the edge within about 30 seconds, and a removed custom domain is cleared within 15 minutes. With no valid origins the edge sends `frame-ancestors 'none'`.
- Browsers enforce framing through the `Content-Security-Policy: frame-ancestors` header on the portal page, which the edge sends (by default `'none'`). Check that the portal loads in your frame before you rely on it.
