1pass

ν•œκ΅­μ–΄

English

ν•œκ΅­μ–΄

English

ν…Œλ§ˆ

🌐 Web Integration Track ​

Source: en/tracks/web.md Β· Live: https://docs.1pass.dev/en/tracks/web LLM-sanitized: internal links absolutized, VitePress containers β†’ admonitions, line numbers in the Jump-to Index reference this rendered file (1-indexed).

πŸ“ Jump-to Index ​

  • L30-L43: ## The four core promises
  • L44-L54: ## Step 1 Β· Register the app
  • L55-L91: ## Step 2 Β· Integration patterns
    • L57-L81: ### SPA / client-side (recommended)
    • L82-L91: ### Server-side (Next.js / Rails / Express)
  • L92-L121: ## Step 3 Β· Avoid the web-specific pitfalls
  • L122-L131: ## Step 4 Β· Pre-build checks
  • L132-L141: ## Common reference (track-agnostic)
  • L142-L149: ## Hand the whole thing to an AI

🌐 Web Integration Track ​

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

πŸ’‘ Tip: Is this the right track?

The four core promises ​

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

⚠️ Warning: Whether you split or share client_id β€” the user-identity key is canonical_sub If you split client_id per surface, the same user receives a different pairwise sub per client; if you share one client_id, you get the same sub. Either way, if the RP keys users by sub, the second-surface login in a split setup can break with AlreadyLinkedError.

β†’ Always identify a person by canonical_sub (always emitted by userinfo), which is identical across all clients. Details: Sub policy

Step 1 Β· Register the app ​

⚠️ Warning: 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 ​

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

bash
npm install @logi-auth/browser
ts
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.

StackGuideCore
Next.js (App Router)integrations/nextjsRoute Handler + iron-session pattern
Rails 8integrations/railsDirect OAuth client (no omniauth). ⚠️ With Hotwire/Turbo, data-turbo="false" is required
Express.jsintegrations/expresscookieParser + crypto PKCE

Step 3 Β· Avoid the web-specific pitfalls ​

⚠️ Warning: ⚠️ 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.

Step 4 Β· Pre-build checks ​

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.

μ΅œμ’… μˆ˜μ •:

Identityκ°€ μ œν’ˆμ˜ μ‹ λ’°λ₯Ό λ§Œλ“­λ‹ˆλ‹€.

Β© 2026 Dcode Labs Β· logi by 1pass