⭐ Quickstart for Agents (RP 통합 런북)
이 페이지의 위치 AI 에이전트가 "이 프로젝트에 logi(1pass) 로그인 붙여줘" 라는 요청을 받으면 가장 먼저 이 페이지를 fetch 하세요. docs.1pass.dev 의 60+ 다른 페이지는 모두 여기서 분기되는 reference 입니다. 본 페이지는 "무엇을 어떤 순서로 / 어떤 트랙에서 / 무엇을 절대 하지 말지" 만 담습니다. 디테일·코드 예시는 전부 link out — 본문에 코드 한 줄도 인라인하지 않습니다.
작업 시작 전 변경 로그 한 번 확인 (deprecated 패턴 회피, F8 참고).
Step 0 — 트랙 자동 감지 + 사용자 확인
본격 작업 시작 전에 트랙 한 개를 확정하세요. 트랙이 정해지지 않으면 잘못된 SDK 를 깔게 됩니다.
| 파일/시그니처 | 트랙 |
|---|---|
Info.plist, *.xcodeproj, Package.swift | 📱 mobile (iOS Swift) |
build.gradle*, AndroidManifest.xml | 📱 mobile (Android Kotlin) |
pubspec.yaml + flutter: 키 | 📱 mobile (Flutter) |
package.json + react-native 의존성 | 📱 mobile (React Native) |
Gemfile + rails | 🌐 web (Rails) |
package.json + next 의존성 | 🌐 web (Next.js) |
package.json + express 의존성 | 🌐 web (Express) |
| 위에 해당 없음 / CLI · 데몬 · webhook 수신만 | 🔧 api |
여러 개가 동시에 잡히면 사용자에게 물어보세요 — 추측 금지. 감지 결과는 작업 시작 전 사용자 confirm 받으세요.
트랙별 가이드: 📱 mobile · 🌐 web · 🔧 api.
책임 표기 규칙
각 step 헤더에 다음 라벨이 붙습니다:
- [agent] — agent 가 코드로 끝낼 수 있는 작업
- [human] — 사용자가 콘솔/시크릿 보관처에서 직접 해야 하는 작업. agent 는 "이제 사용자 차례입니다, 다음 작업: ..." 으로 멈추세요
- [agent + human] — agent 가 준비하고 사용자가 1회 클릭/승인하는 작업
실행 순서 8단계
Step 1 · Client type 결정 — [agent]
⚠️ 등록 전에 결정 의무. logi 는 client type 을 등록 시 immutable 로 잠급니다 (public-vs-confidential 선택 후 변경 불가). 잘못 등록하면 새 RP 를 다시 만들어야 합니다.
트랙 + 시크릿 보관 가능성에 따라 결정:
| 트랙 | client type | 이유 |
|---|---|---|
| 📱 mobile | Public + PKCE | 앱 바이너리에 client_secret 노출 불가 (RFC 8252) |
| 🌐 web (SSR, 백엔드 있음) | Confidential + PKCE | 서버에서 시크릿 보관 가능 |
| 🌐 web (SPA only, 백엔드 X) | Public + PKCE | 브라우저 번들에 시크릿 노출 불가 |
| 🔧 api (server-to-server) | Confidential + device flow / PAK | logi 는 client_credentials grant 를 지원하지 않음 (errors.md) |
세부 결정 규칙: oauth/public-vs-confidential, oauth/public-clients, oauth/recommended-architecture.
Step 1.5 · Scope 결정 — [agent]
RP 가 logi 로부터 받을 사용자 데이터 범위. 등록 시 allowed_scopes 로 박힙니다 — drift 동작 (scopes.md) 숙지 필수.
- 일반 RP 시작점:
openid profile email(대부분 충분) - 추가 필요 시:
phone, custom namespace scope - drift 동작: 요청 scope 중
allowed_scopes에 없는 것이 있으면 기본 정책(block)에서는invalid_scope로 거부됩니다. 관리자가log_only/alert로 완화한 앱만 silent drop 후 진행 — 요청 scope 와 등록 scope 를 처음부터 일치시키세요
검증: 결정한 scope 가 등록 시 allowed_scopes 와 일치, 코드의 authorize 요청 scope 도 동일.
Step 2 · RP 앱 등록 — [human] (CLI 사용 시 [agent + human])
Step 1·1.5 결정한 type + scope 으로 콘솔/CLI 에서 RP 등록 → client_id (+ confidential 이면 client_secret) 발급. agent 는 시크릿을 자기 메모리에 저장하지 말고 사용자에게 "1Password / Keychain / .env 어디에 저장할지" 물어보세요.
- 콘솔 가입 / 앱 생성: guide/registering-apps
- CLI 자동화: cli/apps, cli/login
검증: client_id 가 logi_ 로 시작. confidential 이면 client_secret 이 logi_secret_ 로 시작.
Step 3 · 트랙별 코드 드롭인 — [agent]
여기가 agent 가 가장 많은 코드를 쓰는 step. 본인 트랙에 해당하는 페이지 1개만 적용하세요. 여러 트랙 페이지를 동시에 머지하면 deprecated 패턴이 섞입니다.
| 트랙 / 스택 | 페이지 |
|---|---|
| iOS Swift | integrations/swift |
| Android Kotlin | integrations/android (+ kotlin addendum) |
| Flutter | integrations/flutter |
| React Native | integrations/react-native |
| Rails 8 | integrations/rails |
| Next.js (App Router) | integrations/nextjs |
| Express.js | integrations/express |
| 로그인 버튼 UI | integrations/buttons |
검증: npm run build / bundle exec rails routes / Xcode build 등 빌드 통과.
Step 4 · PKCE + state 구현 검증 — [agent]
logi 는 S256 만 수락. plain 거부. SDK 를 그대로 썼다면 보통 OK 이지만 직접 구현했다면 점검 필수.
- 상세: oauth/pkce
- 표준 흐름: oauth/flow
- 보안 요건: guide/security
검증 체크포인트:
code_verifier가 [43, 128] 자 길이의 URL-safe base64 (RFC 7636)code_challenge_method=S256가/oauth/authorize요청에 포함code_verifier가 세션/Keychain 에 저장되고/oauth/token콜에 다시 사용됨state가 난수로 생성되고 세션에 저장 + 콜백에서 검증 (F3 회피)id_token검증에iss="logi"+aud=LOGI_CLIENT_ID둘 다 체크 (F4 회피)
Step 5 · redirect_uri 등록 — [agent + human]
🚨 OAuth #1 에러 (OneUptime 통계). 이 step 을 대충 하면 production 에서 무조건 터집니다.
agent 가 RP 가 사용할 redirect_uri 목록을 모두 나열해서 사용자에게 콘솔에 등록하라고 알려주세요:
- local dev — 예:
http://localhost:3000/auth/logi/callback - staging — 예:
https://staging.example.com/auth/logi/callback - prod — 예:
https://example.com/auth/logi/callback - mobile (custom scheme) — 예:
com.example.myapp://oauth/1pass/callback
규칙 — 모두 완전 일치 (trailing slash · 대소문자 · query · port 까지). 와일드카드 ❌.
- 등록값 검증 가이드: oauth/redirect-uri-verification
- 트러블슈팅: guide/troubleshooting, oauth/troubleshooting
검증: 콘솔에 등록된 URI 목록과 코드의 LOGI_REDIRECT_URI 환경변수가 글자 단위로 일치.
Step 6 · Webhook receiver + 서명 검증 — [agent]
🚨 Agent 가 가장 자주 빼먹는 step. "verify signature" 를
// TODO로 두면 RP 가 위장 webhook 에 노출됩니다. 결과물에TODO코멘트가 남아 있으면 step 미완료입니다.
- 이벤트 카탈로그 / receiver 골격: guide/webhooks
- HMAC 서명 검증 (두 가지 형식 모두 받아야 함): guide/webhook-verification
- 검증된 템플릿 (Rails/Express/Next.js): templates/webhook
- polling 보완: oauth/polling-events-api
- 이벤트 일관성: oauth/event-delivery
검증: X-Logi-Signature 검증 실패한 요청을 401 로 떨어뜨리는 테스트 케이스가 PR 에 포함되어야 함.
Step 6.5 · Refresh token 회전 처리 — [agent]
logi 는 모든 응답에 새 refresh token 발급 + 재사용 감지 시 family 전체 폐기. RP 가 회전을 처리하지 않으면 한 번의 네트워크 실패로 사용자 강제 로그아웃이 발생합니다.
- 표준 흐름 (재사용 감지 시
400 invalid_grant+ family revoke): oauth/flow - public client 회전 동작: oauth/public-clients
- 저장 가이드 (security.md §4 Refresh Token 저장): guide/security
- Apple/Google upstream refresh 정책 (별개 주제): oauth/refresh-token-rotation
검증:
- 매
/oauth/token응답의 새refresh_token으로 즉시 교체 저장 - 저장 위치: 서버는 암호화 DB, 모바일은 Keychain (iOS) / Keystore (Android), 웹은 HttpOnly Secure SameSite=Strict 쿠키
400 invalid_grant수신 시 = family revoke 또는 만료 → 사용자 재로그인 유도 (조용히 무한 재시도 금지)
Step 7 · First-time signup 폼 — [agent]
logi 는 sub + email (+ nickname) 정도만 줍니다. RP 가 추가 필드 (역할 / 조직 / 약관 동의 등) 가 필요하면 첫 로그인 1회만 받는 폼을 구현하세요. 매번 받으면 UX 가 깨집니다.
- 권장 패턴: integrations/first-time-signup
- 사용자 식별 규칙: oauth/sub-policy
- canonical_sub 마이그레이션: oauth/rp-migration-guide
검증: 같은 logi 계정으로 로그아웃→재로그인 했을 때 폼이 다시 뜨지 않음.
Step 8 · End-to-end 테스트 + 에러/rate limit 처리 — [agent + human]
전체 플로우를 실제 브라우저/디바이스로 검증 + 운영 시 마주칠 에러 코드와 rate limit 를 코드 레벨에서 처리:
- 시나리오 체크리스트: guide/testing
- 사고 직전 점검: oauth/rp-health
- 데모로 비교: guide/demo-page-walkthrough
- 에러 코드 카탈로그 (logging 포맷 포함): oauth/errors
- Rate limit 정책 + 백오프 권장: guide/rate-limits
- 응답 헤더 신호 (
X-Logi-*): oauth/response-headers
검증 (full loop):
/auth/logi/start→/oauth/authorize리다이렉트- logi 앱 푸시 승인 또는 QR 스캔
- RP 콜백 도착 →
/oauth/token교환 성공 →id_token검증 통과 (iss+aud) /oauth/userinfo호출 → user 객체 수신- webhook receiver 에
user.updated가 도착하고 서명 검증 통과 429응답 시Retry-After헤더 따라 backoff 동작 (sleep + 재시도)
트랙별 분기 테이블
각 step 이 트랙별로 어떻게 다른지 한눈에:
| Step | 📱 mobile | 🌐 web | 🔧 api |
|---|---|---|---|
| 1 client type | Public + PKCE 고정 | Confidential 권장 (SPA만은 Public) | Confidential + device/PAK |
| 1.5 scope | openid profile email 기본 | openid profile email 기본 | 최소 (profile 정도) |
| 2 RP 등록 | ✅ Public | ✅ Confidential | ✅ Confidential |
| 3 코드 드롭인 | swift / kotlin / flutter / RN | rails / nextjs / express | api 트랙 페이지 |
| 4 PKCE + state | 필수 | 필수 (SPA·SSR 둘 다) | device flow 는 PKCE 불필요 |
| 5 redirect_uri | custom scheme 권장 | https URL | 해당 없음 (device flow) |
| 6 webhook | ✅ | ✅ | ✅ (가장 자주 쓰이는 트랙) |
| 6.5 refresh 회전 | ✅ Keychain/Keystore | ✅ HttpOnly 쿠키 | ✅ 암호화 DB |
| 7 first-time signup | ✅ | ✅ | 보통 불필요 (UI 없음) |
| 8 e2e | 디바이스 실기기 + 카톡/네이버 escape | localhost + staging | curl 만으로 충분 |
🚨 알려진 함정 (F1-F8) — 빈도순
이 카탈로그를 무시하면 production 사고로 직결됩니다.
F1. redirect_uri 미스매치 (OAuth #1 사고)
- 증상:
redirect_uri_mismatch,invalid_grant, 콜백 페이지에 도착 못 함 - 원인: trailing slash 차이, scheme (
httpvshttps), port, 대소문자, query string - 회피: oauth/redirect-uri-verification, guide/troubleshooting
F2. Webhook signature 생략 (// TODO: verify)
- 증상: 위장 webhook 으로 RP DB 가 더럽혀짐, prod 사고 후 audit 에서 발견
- 원인: Agent 가 receiver 만 짜고 검증을 미룸
- 회피: guide/webhook-verification — 두 가지 서명 형식 모두 처리해야 함. 검증된 템플릿 사용: templates/webhook
F3. state 파라미터 누락/검증 안 함
- 증상: CSRF 로 공격자가 자기 logi 계정을 피해자 RP 세션에 바인딩
- 원인: authorize 요청에
state없거나, 콜백에서 세션 저장값과 비교 안 함 - 회피: guide/security#state
F4. id_token 검증에서 iss / aud 생략
- 증상: 다른 OIDC IdP 의 토큰을 logi 토큰으로 받아들이는 confused deputy
- 원인: JWT 서명만 검증하고 claim 검증 누락
- 회피: oauth/jwks, guide/security
F5. Refresh token 재사용 → family revoke 미처리
- 증상: 한 번의 네트워크 실패 후 모든 사용자가 강제 로그아웃,
400 invalid_grant무한 재시도 - 원인: 회전 후 새 refresh 로 교체 안 함 또는 family revoke
400 invalid_grant를 일반 에러처럼 재시도 - 회피: oauth/flow (재사용 감지 → family revoke + 400 spec), oauth/public-clients
F6. iOS universal-link 호스트 충돌
- 증상: ainote 2026-05-15 사고 — 진행 중 다른 deep link 가 OAuth 파서에 주입돼 가짜
missingCode - 원인: RP 앱이 IdP 와 같은 호스트의 universal link 를 클레임
- 회피: 콜백은 custom scheme (
com.example.myapp://oauth/1pass/callback) — integrations/swift, integrations/react-native, guide/universal-links
F7. 카톡/네이버 인앱 브라우저
- 증상: 인앱 브라우저 안에서 OAuth 가 막힘 (passkey/SSO 안 됨)
- 회피: escape 라우트 사용 — guide/demo-page-walkthrough
F8. Public client 에 client_secret
- 증상: 모바일 앱 / SPA 바이너리에 시크릿이 박혀서 reverse engineering 노출
- 회피: Public + PKCE only — oauth/public-clients
부가 함정 (iOS scheme / Android App Link 호스트 공유) 는 integrations/swift 와 integrations/android 의 함정 섹션 참조.
✅ 작업 완료 self-verify 체크리스트
작업이 끝났다고 사용자에게 보고하기 전에 agent 가 직접 확인할 8개 항목:
- [ ] Step 1·1.5 client type + scope 결정 근거가 PR description 에 기록됨, registration 결과와 일치
- [ ] Step 2
client_id가logi_로 시작 — 콘솔/CLI 등록 완료, 시크릿은 1Password/Keychain/.env에 저장 (코드/git X) - [ ] Step 3 해당 트랙 페이지 1개만 적용 — 빌드 통과
- [ ] Step 4
code_challenge_method=S256,state검증,id_token의iss+aud검증 모두 통과 - [ ] Step 5 redirect_uri 목록 (local / staging / prod / mobile scheme) 모두 콘솔 등록 + 환경변수와 글자 단위 일치
- [ ] Step 6 webhook 서명 검증 코드에
TODO코멘트 0건, 401 테스트 케이스 포함 - [ ] Step 6.5 refresh token 회전 — 새 refresh 즉시 교체 저장 +
400 invalid_grant수신 시 재로그인 유도 (family revoke 또는 만료) - [ ] Step 7·8 first-time signup 폼이 재로그인에서 안 뜸, e2e 6단계 통과 (authorize → 승인 → callback → token → userinfo → webhook + 429 백오프)
8개 중 하나라도 미체크면 사용자에게 "미완료입니다, 다음 step 진행해주세요" 로 보고하세요. 거짓 "완료" 보고 금지.
❌ 하지 말 것 (Anti-patterns)
다음은 production 직전에 반드시 회피해야 하는 패턴들입니다. agent 가 PR 을 만들 때 이 항목 중 하나라도 들어가면 PR 을 self-block 하세요.
- ❌ Implicit Flow 사용 — logi 는 거부. Authorization Code + PKCE 만 지원
- ❌ Password Grant 사용 — logi 는 거부
- ❌
client_secret을 클라이언트 (모바일 바이너리 / SPA 번들 / 공개 git repo) 에 노출 - ❌ redirect_uri 와일드카드 / 부분 매칭 — 완전 일치만 통과
- ❌ Webhook 서명 검증 생략 또는
// TODO: verify - ❌ PKCE
plain사용 —S256만 수락 - ❌
state파라미터 생략 또는 검증 누락 — CSRF 노출 (F3) - ❌
id_token검증에서iss/aud생략 — 토큰 위조 노출 (F4) - ❌ refresh token 무한 재시도 — family revoke 무시하면 사용자 강제 로그아웃 사고
- ❌ 여러 트랙 페이지를 동시에 머지 — deprecated 패턴 섞임
유지보수 안내 (stale skill 방지)
이 페이지와 함께 배포되는 skill/template 들은 시간이 지나면 stale 됩니다. 작업 시작 시 다음 2가지를 확인:
- reference/changelog 의 최근 항목 — 새 grant type / deprecated scope / breaking change 확인
- guide/ai-assistants — Claude Code / Cursor / Codex 용 최신 skill 카탈로그
3개월 이상 cache 된 skill 은 한 번도 안 본 deprecated 패턴을 land 할 수 있습니다. 갱신 의무.
다음 단계
- 등록 → guide/registering-apps
- 5분 quickstart (사람용) → guide/quickstart
- 트랙 선택 → tracks/index
- AI 어시스턴트 skill 카탈로그 → guide/ai-assistants
- 변경 로그 (작업 시작 전 fetch 권장) → reference/changelog