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.

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

Browser lands on redirectUrl with token=… and the same state you sent (if any).

4

Verify

Your backend verifies the JWT (shared secret) or calls /api/auth/verify, then issues your own session.

Login URL and query parameters

Always URL-encode redirectUrl. Example pattern:

const login = new URL('https://YOUR_AUTH_HOST/login') login.searchParams.set('redirectUrl', 'https://your-app.example.com/auth/callback') login.searchParams.set('state', crypto.randomUUID()) window.location.href = login.toString()
  • 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 · Verify API

POST 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 res = await fetch('https://YOUR_AUTH_HOST/api/auth/verify', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ token }), }) const body = await res.json() if (body.code === 0 && body.data?.access_token) { // trusted login — use body.data.user for display; body.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

function handleLogin() { const state = crypto.randomUUID() sessionStorage.setItem('oauth_state', state) const callback = window.location.origin + '/auth/callback' const url = new URL('https://YOUR_AUTH_HOST/login') url.searchParams.set('redirectUrl', callback) url.searchParams.set('state', state) window.location.href = url.toString() }

Callback route

function AuthCallback() { useEffect(() => { const params = new URLSearchParams(location.search) const token = params.get('token') const state = params.get('state') if (!token) return if (state !== sessionStorage.getItem('oauth_state')) { throw new Error('Invalid state') } sessionStorage.removeItem('oauth_state') void verifyTokenAndCreateSession(token) }, []) return <div>Signing you in...</div> }

Practices

  • Whitelist every production callback origin in ALLOWED_REDIRECT_URLS; use wildcards sparingly
  • Generate a fresh state per attempt; reject callbacks with missing or stale state
  • 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