Create a WorkOS Organization, attach and verify its domains, and use domain matching to route users to the correct SSO connection

Documented steps

1. Create the organization: POST https://api.workos.com/organizations with 'Authorization: Bearer sk_...' and body {"name":"Customer Inc","domain_data":[{"domain":"customer.com","state":"pending"}]}.
2. Set a domain's state to "verified" at creation ONLY if you have already confirmed the customer controls it — WorkOS puts that responsibility on you.
3. For untrusted domains leave state "pending". The returned domain object includes verification_prefix, verification_token, and verification_strategy ("dns") for DNS TXT verification, or you can delegate verification to the customer via the Admin Portal domain_verification intent.
4. List organizations: GET https://api.workos.com/organizations with optional limit (1-100, default 10), before/after cursors, order, domains, and search.
5. Fetch one: GET /organizations/{id}, or GET /organizations/external_id/{external_id} if you set an external_id.
6. Update (flip a domain to verified, rename, set metadata): PUT https://api.workos.com/organizations/{id}, which accepts name, domain_data, metadata, external_id, stripe_customer_id, and allow_profiles_outside_organization.
7. At login, WorkOS matches the authenticating user's email domain against organization domains to select which Organization and Connection to route to.
8. Only domains in state "verified" participate in that routing match — pending domains are rejected by default to prevent domain-squatting impersonation.
9. To permit users whose email domain matches no organization domain (contractors, consultants), set allow_profiles_outside_organization to true via the update endpoint, and understand you are widening who can enter that org.
10. Reference: https://workos.com/docs/reference/organization
11. Reference: https://workos.com/docs/sso