Skip to content
Dashboard
Theme
Theme

Intents

Use the supported portal intents and interpret setup states.

View Markdown

An intent limits what a portal session may do. The current contract accepts domain_verification, sso, dsync, edit_connection, migration and log_streams.

Intent Workflow
domain_verification Add and verify organization domains
sso Domain setup, configure a connection, test and activate it
dsync Create a directory and check its first SCIM request
edit_connection Reopen one existing connection named in the link
migration Complete imported connection metadata and directory handoff
log_streams Add and remove log destinations for the organization (plans with log streams)

edit_connection requires the link’s connection and pins the session to that connection. It cannot create connections; invites do not accept this intent. The migration intent reaches imported resources in its organization; it supplies missing metadata only for an imported draft SAML connection with no existing IdP metadata. A connection-pinned session stays pinned. Read the WorkOS metadata step and migration levers.

The context reports incomplete steps. An untested activation produces test_sign_in_pending with HTTP 409. Other portal states describe what the admin should do next; the error catalogue’s internal zero status for a portal state is never an HTTP response status.

GET /v1/organizations/{org}/status (secret key, organizations:read) returns the same checklist the portal shows, for each of the organization’s allowed intents, or every intent when it has none. edit_connection is never listed: it is the checklist of one connection named by a link, not of the organization. Each intent has complete and its steps in order, each with a state of todo, pending or done.

Intent Steps
domain_verification add_domain, verify_domain
sso verify_domain, configure_connection, test_sign_in, activate_connection, register_standby_acs
dsync create_directory, first_scim_request
migration configure_connection, test_sign_in, activate_connection, register_standby_acs for imported connections
log_streams add_log_stream

The SSO steps follow the most advanced connection. register_standby_acs is optional: sso is complete once the domain is verified and a connection is active. An active connection whose IdP settings changed after its test shows test_sign_in as pending until it is tested again.

Configure allowed success destinations for the workflow, then check the resource’s actual status when the admin returns. A return redirect alone does not prove that a connection is active or provisioning succeeded.

Use the test and Doctor guide for the shared management and portal results, worker-delayed activation and supported fix-mail operation.

An attached portal profile further restricts the allowed providers and features. It does not grant an intent the link lacks. Required mappings are checked separately for each feature selected in the explicit Finish request. Completing a profile-backed link ends its editing authority; it does not deactivate an existing connection or interrupt sign-ins.

Signing-key rotation has separate acknowledgement, next-key test, confirmation and activation steps. An ordinary successful connection test does not qualify as the rotation’s next-key proof.