🔧 API · CLI · 서버 간 통신 트랙

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

📍 Jump-to Index

• L29-L77: ## 패턴별 분기
  • L31-L41: ### 1. 머신 ↔ 머신 (CLI / 데몬 / CI)
  • L42-L49: ### 2. AI 에이전트 / LLM
  • L50-L59: ### 3. 백엔드 → logi API
  • L60-L69: ### 4. logi → 백엔드 (Webhook)
  • L70-L77: ### 5. 관리 API (Org / Team / App 관리)
• L78-L88: ## 공통 레퍼런스
• L89-L94: ## AI 에게 통째로 던지기

---

🔧 API · CLI · 서버 간 통신 트랙

사용자가 직접 브라우저로 로그인하지 않는 모든 케이스. CLI · 데몬 · CI/CD · AI 에이전트 · webhook 수신.

💡 Tip: 이 트랙이 맞나요?

• ✅ 맞음: 백엔드끼리만 통신, 또는 CLI 도구가 사용자 대신 logi 호출
• ✅ 맞음: AI 에이전트(Claude/Cursor/Codex) 가 MCP 로 logi 조작
• ❌ 모바일 앱 → 📱 모바일 트랙
• ❌ 사용자 브라우저 로그인 → 🌐 웹 트랙

패턴별 분기

1. 머신 ↔ 머신 (CLI / 데몬 / CI)

사용자 인터랙션이 가능하지만 브라우저는 못 띄우는 환경.

• OAuth 2.0 Device Flow (RFC 8628) — TV / CLI / IoT 표준
  • Device Flow 가이드
• logi CLI — logi login 으로 디바이스 코드 받아 브라우저 승인
  • 빠른 설치: gem install logi-cli
  • CLI 설치 · 로그인 · 앱 관리 · 팀 관리
  • CI/CD 에서 사용 — non-interactive 토큰 주입 패턴

2. AI 에이전트 / LLM

Claude Code · Cursor · Codex 가 자연어로 logi 조작.

• MCP (@logi/mcp) — Model Context Protocol 서버
• AI 어시스턴트 통합 — llms.txt / llms-full.txt 표준 엔드포인트
• 📥 /llms-full.txt — 전체 문서 LLM-friendly 패키지 (~500 KB)

3. 백엔드 → logi API

사용자 토큰 검증 · 사용자 정보 조회 · 권한 변경.

• API 레퍼런스 (OpenAPI) — 인터랙티브 Scalar 뷰어
• Token Introspection & JWKS — id_token 검증 / 공개키 fetch
• Polling Events API — 사용자 이벤트(탈퇴/연결해제) pull 방식
• POST /api/v1/me/anonymous_swap — 익명 계정을 canonical(이메일·SSO) 계정으로 swap/merge. 자세한 흐름은 Anonymous → Canonical Account Swap.
• GET/POST /developer/applications/:id/{redirect_uri_verifications,verify_redirect_uri} (세션) · GET/POST /api/v1/admin/applications/:id/{redirect_uri_verifications,verify_redirect_uri} (admin) — RP redirect_uri 도메인 소유권 검증 (DNS TXT + .well-known 2-prong). Redirect URI Verification.

4. logi → 백엔드 (Webhook)

logi 가 RP 백엔드로 비동기 이벤트 push.

• Webhook 연동
• HMAC 서명 검증
• Event Delivery (3-tier)
• Webhook 서명 키 회전
• RP Health Check Protocol — webhook 과 별개의 active probe (logi → RP /health HMAC handshake). RP 살아있음을 logi 가 능동 확인.

5. 관리 API (Org / Team / App 관리)

logi 콘솔이 하는 모든 일을 API 로.

• API 레퍼런스 — 관리 API 전체 엔드포인트

---

공통 레퍼런스

• 핵심 개념
• Public vs Confidential 결정
• 오류 코드 · Rate Limits
• 보안 Best Practices · Threat Model
• demo.1pass.dev/oauth — PKCE 라운드트립 walking sample (CLI / 서버 통합도 동일한 PKCE shape 을 따름)
• Demo 페이지 둘러보기 — 시나리오별 흐름 정리

---

AI 에게 통째로 던지기

@/llms-full.txt 를 LLM 에 붙이고:

"logi MCP 서버를 Claude Code 에 연결해줘. 그리고 내 CLI 스크립트가 device flow 로 토큰 받아서 /api/v1/applications 호출하게 해줘."