# Intents

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](/migrate/from-workos/) and [migration levers](/migrate/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.

<a id="organization-status"></a>

## Organization setup 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](/hosted-portal/connection-doctor/) for the shared management and portal results, worker-delayed activation and supported fix-mail operation.

An attached [portal profile](/hosted-portal/profiles/) 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](/sso/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.
