Hosted vs Embedded
Should users sign in on id.avnology.net/sign-in?client_id=... or inside your app via <SignIn/>?
Hosted vs Embedded
Avnology ID ships two integration shapes. Hosted is the primary, recommended flow for v1. Embedded is supported for apps that specifically need it.
Quick answer
Default to hosted. Send users to
id.avnology.net/sign-in?client_id=..., handle the callback, done. Switch to embedded only if you have a specific reason (below).
The two shapes
Hosted (Universal Login)
Your app redirects users to https://<Domain id="app"/>/sign-in?client_id=<your_client_id>&redirect_uri=...&response_type=code&state=...&code_challenge=... and they come back to your app with an authorization code you exchange for a session.
Everything auth-related happens on <Domain id="app"/>: the page chrome is Avnology-branded (or your brand if you've set up custom domains). All 37 authentication flows -- password, passkey, social, SSO, SAML, magic link, SMS OTP, WebAuthn, device flow, MFA prompts, account recovery -- are rendered by our hosted pages.
Embedded
You mount <SignIn/> / <SignUp/> / the @avnology/login-widget inside your own app. Auth happens without a redirect; the form lives in your DOM.
Your app Avnology API
──────── ────────────
│ │
│ (user types email/pass in │
│ <SignIn/>) │
│ │
│ POST /v1/flows/login │
│ ─────────────────────────> │
│ <───── flow w/ UI nodes ── │
│ │
│ POST /v1/flows/login/ │
│ :submit w/ credentials │
│ ─────────────────────────> │
│ <───── session ────────── │
│ │Decision matrix
| Concern | Hosted | Embedded |
|---|---|---|
| Time to first working login | ~10 min | ~45 min |
| Setup work | Register OAuth client + implement callback | Install @avnology/id-elements, wire React context, handle loading / error / MFA / passkey UI |
| Full auth method catalogue | Yes, all 37 flows out of the box | MVP has password + social; passkey / SSO / MFA stepping wire up one at a time |
| Brand customization | Full (custom domain + branding tokens) | Full (your app's DOM) |
| Page hopping | User sees a redirect to id.avnology.net | No redirect, looks like one app |
| Mobile deep-link handling | ASWebAuthenticationSession / Custom Tabs standard | You own it |
| Security review surface | Small (two redirects, callback handler) | Large (every field you render) |
| Compliance evidence | Our SOC 2 covers the entire sign-in surface | You own the surface; our SOC 2 covers the API only |
| Breaking changes | We can ship a new MFA method, users get it automatically | You have to update the widget + redeploy |
When to pick hosted
Pick hosted if any of these are true:
- You want the shortest path to working auth. (Most common.)
- Your designers haven't yet decided what sign-in should look like.
- You want new auth methods (passkeys, SSO, device flow) for free as we ship them.
- You want the smallest possible security review surface.
- You're a consumer-first product where users will trust a polished auth page.
When to pick embedded
Pick embedded only if one of these is true:
- Your sign-in screen is a core brand asset with a specific design language that cannot tolerate a redirect to a different origin.
- You're inside a web view (native mobile shell) where redirects are hard.
- You're building a CLI or programmatic client where device flow is more appropriate (that's a third option -- see Device flow).
- Your enterprise customer refuses to let their employees see any domain other than yours during auth. (Custom domains solve this without going embedded -- see below.)
"Can I have the hosted flow look exactly like my app?"
Yes. Custom domains + branding cover 99% of the "don't show them our domain" requirement. Users hit login.your-company.com, the page chrome is fully your brand (logo, colors, fonts, CSS) -- but it's still our hosted flow under the hood, which means you still get every new auth method for free. This is the recommendation for 9 out of 10 enterprise design concerns.
How to pick a quickstart
- Hosted: Quickstart -- hosted universal login (all SDK quickstarts assume hosted by default).
- Embedded: React integration guide + components reference.
You can mix
An app can have a hosted Universal Login for normal sign-in and an embedded <SignIn/> inside a settings panel to re-auth for sensitive actions. Both use the same session cookie; both write the same audit events.