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.
Organization setup status
Section titled “Organization setup status”GET / (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.