Home Realm Discovery

Home Realm Discovery (HRD) uses the email domain to decide whether a user should be routed to an upstream enterprise provider or fall back to standard hosted auth.

Endpoint

POST /api/auth/lookup-email

Request

{
  "email": "user@acme.com"
}

Response

When the domain is verified and mapped to an enabled upstream provider:

{
  "connection_id": "okta-acme",
  "provider_name": "Acme Okta",
  "domain_verified": true,
  "auth_method": "upstream"
}

Fallback behavior:

• auth_method: "password" when the domain is verified but no enabled upstream route is available
• auth_method: "oauth" when no verified route exists for the email domain

How to configure it

1. Create a domain route with POST /api/organizations/:org_slug/domain-routes
2. Verify the domain route with POST /api/organizations/:org_slug/domain-routes/:domain_id/verify
3. Create an upstream provider with POST /api/organizations/:org_slug/upstream-providers
4. Patch the domain route so upstream_provider_id points at that provider

Client usage

Typical flow:

1. Ask for the user’s email
2. Call POST /api/auth/lookup-email
3. If auth_method === "upstream", send the user to /auth/:provider?connection_id=...
4. Otherwise continue with password or hosted OAuth UX