Signet
Sign in

Guide

Integrate your apps

Treat this host as the identity provider: your app only needs a login link, a callback route, and token verification. No password storage in consumer services.

For interactive OAuth-style experiments, use OAuth Playground; the steps below focus on the /login redirect contract and use the hosted SDK helpers.

Flow

1

Redirect

Send the browser to /login with redirectUrl (absolute or same-origin path) and optional state.

2

Sign in

User enters password; TOTP if configured; or WebAuthn-only when enabled. Remember me changes JWT lifetime.

3

Return

`/login`: token + optional state in **query** (`?token=&state=`). `/oauth` (ECDH): encrypted return in **hash** (`#token=&state=`). Prefer `parseLoginCallbackParams(window.location.href)` from the hosted SDK so one path covers both.

4

Verify

Use SDK verifyTokenAtAuthCenter (or explicit shared-secret verification), then issue your own session.

Backend or frontend ownership

  • **Backend-owned session (recommended when the app has a server):** browser starts Signet login, Signet returns to your backend callback for `/login`, backend loads the SDK, parses query token/state, calls `verifyTokenAtAuthCenter`, then issues your own httpOnly session cookie. This is best for admin panels and higher-risk tools.
  • **Frontend-only app (supported for static/SPAs):** browser starts Signet login, callback page loads the SDK, parses `window.location.href`, validates `state`, calls `verifyTokenAtAuthCenter`, strips the callback URL, then stores the returned app token in frontend state/storage. This cannot create an httpOnly session cookie and is better for lower-risk personal tools.
  • **ECDH `/oauth` redirect:** token/state return in the URL hash, so the callback must be handled in browser code first. A server Route Handler cannot read the hash; after client-side parse/decrypt/verify, send only your own session bootstrap data to your backend if needed.
  • **Agent decision rule:** if the target project has a backend/session layer, choose backend-owned session. If it is truly static/frontend-only, choose frontend-only and call out the storage tradeoff. If requirements are unclear, ask which mode the user wants before implementing.

Login URL and query parameters

Always URL-encode redirectUrl. Example pattern:

const signet = await import(/* webpackIgnore: true */ 'https://YOUR_AUTH_HOST/sdk/signet-client.mjs') const state = crypto.randomUUID() const loginUrl = signet.buildLoginUrl({ authCenterOrigin: 'https://YOUR_AUTH_HOST', redirectUrl: 'https://your-app.example.com/auth/callback', state, }) window.location.href = loginUrl
  • redirectUrl — where to send the user after success; must pass redirect allowlist rules when cross-origin.
  • state — optional but recommended; echo it back so your callback can detect CSRF or replay.

Verify tokens

Option A · Shared secret

Use the same JWT_SECRET as this deployment. Verify authenticated, expiry, and optionally iss/sub to match your policy.

import { jwtVerify } from 'jose' const { payload } = await jwtVerify( token, new TextEncoder().encode(process.env.JWT_SECRET!) ) if (payload?.authenticated === true) { // issue your own session cookie / API token }
Lowest latency when the consumer is also yours

Option B · SDK verify API

Call SDK verifyTokenAtAuthCenter; it POSTs JSON { token, audience?, scope? } to /api/auth/verify. The route checks Origin against your redirect allowlist, requires HTTPS for browser calls, and returns the standard envelope: code === 0 with data shaped like an OAuth token response (access_token, token_type, expires_in, user, optional claims).

const signet = await import(/* webpackIgnore: true */ 'https://YOUR_AUTH_HOST/sdk/signet-client.mjs') const result = await signet.verifyTokenAtAuthCenter({ authCenterOrigin: 'https://YOUR_AUTH_HOST', token, audience: 'your-app', }) if (!result.ok) { throw new Error(result.error || 'Signet token verification failed') } const data = result.response.data // trusted login — use data.user for display; data.access_token for APIs
No JWT_SECRET in the consumer; this host performs verification

React sketch

Replace YOUR_AUTH_HOST with your deployed auth base (no trailing slash). Keep state server-side or in sessionStorage only for the duration of the redirect.

Start login

async function handleLogin() { const state = crypto.randomUUID() sessionStorage.setItem('oauth_state', state) const signet = await import(/* webpackIgnore: true */ 'https://YOUR_AUTH_HOST/sdk/signet-client.mjs') const url = signet.buildLoginUrl({ authCenterOrigin: 'https://YOUR_AUTH_HOST', redirectUrl: window.location.origin + '/auth/callback', state, }) window.location.href = url }

Callback route

function AuthCallback() { useEffect(() => { const run = async () => { const signet = await import(/* webpackIgnore: true */ 'https://YOUR_AUTH_HOST/sdk/signet-client.mjs') const { token, state } = signet.parseLoginCallbackParams(window.location.href) if (!token) return if (state !== sessionStorage.getItem('oauth_state')) { throw new Error('Invalid state') } sessionStorage.removeItem('oauth_state') const result = await signet.verifyTokenAtAuthCenter({ authCenterOrigin: 'https://YOUR_AUTH_HOST', token, audience: 'your-app', }) if (!result.ok) throw new Error(result.error || 'Signet token verification failed') await createSessionFromSignet(result.response.data) history.replaceState(history.state, '', signet.stripLoginCallbackFromUrl(window.location.href)) } void run() }, []) return <div>Signing you in...</div> }

Practices

  • Whitelist every production callback origin in ALLOWED_REDIRECT_URLS; use wildcards sparingly
  • Use the hosted SDK for URL building, callback parsing, URL cleanup, and verify API calls; do not duplicate these helpers in consumer apps
  • Generate a fresh state per attempt; reject callbacks with missing or stale state
  • For `/oauth` returns, never rely on `useSearchParams()` / query-only parsers — the token is in the **hash** until you use `parseLoginCallbackParams(fullUrl)`
  • Do not log full JWTs; log correlation ids only
  • Re-verify on privileged actions if your session is long-lived
  • Align JWT_EXPIRES_IN with your risk tolerance; Remember me off caps sessions at 1d
Project Integration - Getting Started