🌐 Web Integration Track

The fastest path to integrating logi in server-side web apps like Next.js, Rails, and Express.

Is this the right track?

✅ Yes: a web service that has a backend and that users reach in a browser
❌ Mobile app → 📱 Mobile App Integration Track
❌ Pure SPA (no backend) → Public Client + PKCE. See public-clients
❌ Desktop SSO (receiving Apple / Google ID tokens directly) → Web SSO (desktop)

The four core promises

Confidential client + client_secret held server-side. Never expose it in the browser bundle.
redirect_uri is https://... or http://localhost — the server callback route path.
Verify state + nonce and issue the session with HttpOnly + Secure cookies.
Keep the app RP and the web RP separate — details: Common / Public Clients · One RP per surface

Step 1 · Register the app

Email verification required before registering an app (RP)

Before you can register an app (RP) in the developer console, you must verify your email. After signing up, click the link in the verification email, or resend it from the console at /account. Registration is blocked until you verify. → App registration guide · Prerequisite

SPA / client-side → register the RP with client_type: public (PKCE-only, no secret).
Server-side (Next.js / Rails / Express) → register the RP with client_type: confidential → you get a client_id + client_secret.
App registration guide
Choosing Public vs Confidential

Step 2 · Integration patterns

SPA / client-side (recommended)

For a pure SPA (token exchange directly in the browser, with no backend callback), use the official SDK @logi-auth/browser@0.1.0:

bash

npm install @logi-auth/browser

import { LogiAuth } from '@logi-auth/browser';

const auth = new LogiAuth({
  clientId: 'logi_xxx',
  redirectUri: window.location.origin + '/auth/callback',
});

// Page A — start login
await auth.signIn();

// Page B — callback page
const tokens = await auth.handleCallback();

For the full API and error classification → SPA Quickstart

Server-side (Next.js / Rails / Express)

Hold client_secret on the server and handle the callback there. logi provides standard OIDC discovery (https://api.1pass.dev/.well-known/openid-configuration), so general OIDC libraries — oauth4webapi, openid-client, next-auth, auth.js — configure themselves automatically from issuer: 'https://api.1pass.dev' alone.

Stack	Guide	Core
Next.js (App Router)	integrations/nextjs	Route Handler + iron-session pattern
Rails 8	integrations/rails	Direct OAuth client (no omniauth). ⚠️ With Hotwire/Turbo, `data-turbo="false"` is required
Express.js	integrations/express	`cookieParser` + crypto PKCE

Step 3 · Avoid the web-specific pitfalls

⚠️ When adding a web surface to an existing mobile RP, you must update the redirect_uri whitelist

When a single client_id is shared by a mobile app and a web surface (safe for a public + PKCE RP), the web callback URL must also be explicitly registered in the RP's redirect_uris whitelist. If it's missing, logi rejects the request immediately:

json

{ "error": "invalid_request", "error_description": "redirect_uri not registered" }

Before you start the web build, always:

bash

# check the currently registered whitelist
logi app show $CLIENT_ID
# if missing, add it (existing URIs are kept; this appends)
logi app update $CLIENT_ID --add-redirect-uri "https://app.example.dev/auth/1pass/callback"
# if you have preview/staging domains, register them too
logi app update $CLIENT_ID --add-redirect-uri "https://preview.example.dev/auth/1pass/callback"
# verify
logi apps verify $CLIENT_ID -r "https://app.example.dev/auth/1pass/callback"

This pitfall commonly happens "when bolting a new web flow onto an RP that was already registered for mobile." For a new RP, register the callbacks for every surface up front in the redirect_uris array of the App registration guide.

Response headers / body signals — Set-Cookie SameSite policy
Web SSO (desktop Apple/Google) — for understanding internals. It is not the starting point for a new RP integration; refer to it only when you want to know how logi handles Apple/Google upstream IdP tokens
QR login (app push approval) — delegate approval from a desktop web RP to the mobile app
Widget SDK (iframe embed) — pattern for embedding the login screen in an iframe
First-login completion form — pattern for your own extra sign-up fields

Step 4 · Pre-build checks

✅ Verify the redirect_uris whitelist — right before build/deploy, run logi apps verify $CLIENT_ID -r "$WEB_CALLBACK_URL" to check each of your production, staging, and preview domains. Baking it into CI is safest (--json + exit code).
RP integration testing
Security best practices (RP side) — state/nonce/CSRF
Troubleshooting
demo.1pass.dev/qr — desktop ↔ mobile QR handoff walking sample (scenario deep-links)
demo.1pass.dev/oauth — desktop OAuth (PKCE) walking sample
Demo page walkthrough — per-scenario flow + clean-CSP pattern

Common reference (track-agnostic)

Hand the whole thing to an AI

Paste @/llms-full.txt into Claude Code, Cursor, or Codex, then say:

"Integrate logi 1pass as an RP into my [Next.js / Rails / Express] web app, using a confidential client + a server-held secret."

→ It generates the env, route, controller, callback handler, and login button UI automatically.

🌐 Web Integration Track ​

The four core promises ​

Step 1 · Register the app ​

Step 2 · Integration patterns ​

SPA / client-side (recommended) ​

Server-side (Next.js / Rails / Express) ​

Step 3 · Avoid the web-specific pitfalls ​

Step 4 · Pre-build checks ​

Common reference (track-agnostic) ​

Hand the whole thing to an AI ​