Auth + Hosted Verify
NEUS supports a signature-based protocol for proofs, and an optional session layer for first-party browser UX.
Two layers
| Layer | Purpose |
|---|
| Protocol signing (proofs) | What verifiers require; described in Signing |
Session (/api/v1/auth/*) | Optional convenience layer to reduce repeated prompts |
Hosted Verify UX (Passkey or Wallet)
When a flow requires human interaction (signature, OAuth linking, proof creation), NEUS provides a hosted UI.
- Users can sign in with a passkey (no wallet extension required) or connect a wallet
- After completion, the hosted UI returns the user to your app
Standardized hosted login URL
Query params:
| Param | Use |
|---|
returnTo=/profile | First-party NEUS app routing only (same-origin, relative) |
returnUrl=https://partner.example/callback | Integrator-controlled redirect target |
mode=popup&origin=https://partner.example | Popup flow with postMessage back to opener |
Do not invent a second hosted login route. intent=login on /verify is the correct implementation.
Session SSOT: GET /api/v1/auth/me
If you use the session layer, treat this endpoint as the single source of truth for:
- Whether the user is authenticated
- The user’s identity pack (subjectId/did/address)
- Onboarding readiness (if provided by the deployment)
Routing contract
| State | Action |
|---|
authenticated: false | Keep hosted login choices visible |
authenticated: true + needsOnboarding: true | Your app decides: prompt profile setup or proceed |
authenticated: true + needsOnboarding: false | Route to returnUrl or your app’s authenticated landing |
Hosted checkout URL configuration
If you run the NEUS API at a custom apiUrl, also set the hosted verify URL explicitly:
<VerifyGate
apiUrl="https://api.neus.network"
hostedCheckoutUrl="https://neus.network/verify"
requiredVerifiers={["ownership-basic"]}
>
<Protected />
</VerifyGate>
Hosted verify must be same-origin with its own passkey RP ID/origin configuration.
- Message type:
neus_login_complete
- Delivery:
window.opener.postMessage(...)
- Origin: restricted to the supplied
origin when it is an absolute HTTP(S) origin
Outage contract
The browser-facing NEUS BFF routes normalize upstream outages:
- Interactive auth routes return
503 for upstream 5xx or transport timeouts
- They include
Retry-After: 10
- They include
X-Neus-Upstream-Status for diagnostics
- They set
Cache-Control: no-store
