Choose Your Integration Pattern

The three ways to integrate Hawcx sign-in, and how to tell which redirect flow you are on.

There are three ways an app signs users in with Hawcx. They look similar — each can involve a "redirect to a Hawcx page and come back with a code" — but they are distinct, and the docs for each live in different places. Pick your pattern first; the rest of the docs follow from it.

The three patterns

SDK-embedded (adaptive)

You render the auth flow inside your own UI with the Hawcx SDK (@hawcx/core / @hawcx/react, or a mobile SDK). start(email) drives a state machine and you render each step. Best when you want auth to live natively inside your app.

Hawcx-hosted / SSO (OIDC)

Your app is a standard OpenID Connect relying party. You send users to Hawcx's hosted /authorize page and exchange the returned code on your backend. Best when you want a hosted login page or standards-based SSO across apps.

Social sign-in

"Continue with Google" (and other OIDC providers) brokered through Hawcx. This rides on top of the hosted OIDC flow — Hawcx brokers the provider behind the hosted screen. Best when you want social buttons without wiring each provider yourself.

These aren't mutually exclusive. A common shape is the SDK-embedded pattern with social sign-in enabled — the SDK runs your primary flow and hands off to the hosted screen only when the user picks a social provider.

Which redirect flow am I using?

All three can bounce the browser to a Hawcx page and back with a code. What differs is who starts the redirect and who exchanges the code:

You are using	The redirect is triggered by	Who exchanges the `code`	Reference
SDK-embedded with social/SSO enabled	the SDK, as a `redirect` step (`window.location.href = step.url`)	the SDK resumes the flow on return; your backend then exchanges the resulting `authCode` (PKCE)	Web API reference → `redirect` step
Hawcx-hosted / SSO (OIDC)	your app, sending the user to `GET /authorize`	your backend, via `POST /oauth2/token` (OIDC token endpoint)	SSO → OIDC
Social sign-in	the hosted screen, brokering the provider on top of the OIDC flow	same as the OIDC flow above	Social Connect

They use different return mechanisms

The SDK's redirect step is not the OIDC /oauth2/token flow. If you built on the SDK (@hawcx/core) and later enable Social/SSO, handle the redirect step in your step renderer (navigate to step.url) — don't try to call the OIDC token endpoint yourself. Conversely, if you are an OIDC relying party, follow the OIDC flow end to end and don't reach for the SDK's step machine.

Not sure which one you want?

Building auth inside your app's own screens? → SDK-embedded. Start with the 5-Minute Integration.
Want a hosted login page or SSO across multiple apps? → Hawcx-hosted / OIDC. See SSO → OIDC.
Want "Continue with Google" and similar? → Social sign-in. See Social Connect.