앱 등록 가이드
Source:
guide/registering-apps.md· Live: https://docs.1pass.dev/guide/registering-apps LLM-sanitized: internal links absolutized, VitePress containers → admonitions, line numbers in the Jump-to Index reference this rendered file (1-indexed).
📍 Jump-to Index
- L45-L52: ## 사전 요건 — 이메일 인증 (2026-05-28~)
- L53-L67: ## 자동 위험 평가 (creation_risk_flags)
- L68-L74: ## Rate limit
- L75-L78: ## CLI / MCP 자동화에서 등록할 때
- L79-L89: ## 등록 폼 필드
- L90-L95: ## 발급 값
- L96-L110: ## Client type
- L111-L120: ## 등록 유형 분류 (Redirect URI 호스트 기준)
- L121-L126: ## Redirect URI 규칙
- L127-L148: ## Production 승급
- L131-L140: ### 신청
- L141-L148: ### 결과
- L149-L158: ## 로그인 방법 제한
- L159-L164: ## 유형 전환
- L165-L182: ## 수정 / 삭제
- L170-L182: ### 콜백 path rename (브랜드 통합, 라우트 정비)
- L183-L190: ## FAQ
- L191-L194: ## 문의
- L195-L202: ## LLM 친화 버전
앱 등록 가이드
앱·scope 등록/관리는 Developer Console (웹) 와
logiCLI 에서 합니다 (MCP 는 현재 앱 조회 + redirect URI 추가/삭제만 지원). 네이티브(iOS/Android) 소비자 앱은 최종 사용자 계정용이며 앱/scope 등록 기능을 제공하지 않습니다.
⚠️ Warning: OAuth 호스트 —
api.1pass.dev로 통일하세요 issuer 와 discovery 는https://api.1pass.dev에 고정입니다:/.well-known/openid-configuration와/.well-known/jwks.json는api.1pass.dev에만 있고start.1pass.dev에선 404, id_token 의iss도https://api.1pass.dev입니다.
/oauth/authorize·/oauth/token·/oauth/userinfo 자체는 두 호스트에서 응답하지만, RP 는 모든 엔드포인트를 api.1pass.dev 로 통일하세요 (issuer 와 일치 → iss 검증·discovery 혼선 방지). ⚠️ 콘솔의 "지금 curl 로 테스트" 스니펫은 콘솔 호스트(start.1pass.dev) 기준으로 생성되니, 호스트를 api.1pass.dev 로 바꿔 쓰는 것을 권장합니다. 권위값은 항상 https://api.1pass.dev/.well-known/openid-configuration 에서 확인.
💡 Tip: CLI 한방 등록 개발자 등록 → 이메일 검증 → RP 등록 → secret 확보까지 CLI 로 끝내려면 CLI 단계별 RP 등록 가이드 (복사용 프롬프트 + 검증 체크리스트 포함) 를 참고하세요.
사전 요건 — 이메일 인증 (2026-05-28~)
logi 는 AI 에이전트가 자동화로 RP 를 양산하는 시나리오를 막기 위해, 이메일 인증된 계정만 RP 등록 가능합니다.
- 가입 직후 confirmation 메일 발송. 인증 링크 클릭 후 RP 등록 활성화.
- 인증 메일 못 받았다면 콘솔
/account또는/console페이지의 "✉️ 인증 메일 보내기" 버튼으로 재발송. - 미인증 상태에서 호출 시: 웹은
/developer/applicationsredirect + alert, API/CLI/MCP 는 HTTP 403{"error":"identity_verification_required","verify_url":"..."}응답.
자동 위험 평가 (creation_risk_flags)
등록 시 RP 메타데이터가 다음 신호와 매칭되면 admin 큐에 위험 표시가 붙습니다. 보안 가이드 의 acknowledgement 게이트를 통과해야 production 승인:
| 신호 | 트리거 |
|---|---|
wildcard_redirect_uri | redirect_uri 에 * 포함 |
sensitive_scope | admin 같은 권한 폭 큰 scope 요청 |
unlisted_scope | 표준 scope (openid/profile:basic/email/phone/offline_access) 외 |
high_volume_developer | 같은 developer 가 7일 안에 5건 이상 등록 |
new_developer_account | developer 계정이 7일 이내 가입 |
suspicious_app_name | test, sample, foo, untitled, app123 등 placeholder 이름 |
위험 신호가 있어도 등록 자체는 통과하지만 status: pending 동안 사용 불가. admin 이 검토 후 명시 "위험 알면서 승인" 으로만 승급.
Rate limit
- POST
/developer/applications— developer 당 시간당 10건 / 일 30건 - POST
/api/v1/applications(CLI/MCP/PAK) — PAK 토큰당 동일 캡
초과 시 HTTP 429 {"error":"rate_limited"} + Retry-After 헤더.
CLI / MCP 자동화에서 등록할 때
자체 스크립트 · logi CLI · MCP 사용 시 X-Logi-Client-Type: cli|mcp|api 헤더 동봉. 감사 로그에 created_via 채널 정확히 기록 → 양산 감지에 활용.
등록 폼 필드
| 필드 | 설명 | 예시 |
|---|---|---|
| 앱 이름 | 동의 화면 표시명 | My App |
| Client type | Confidential / Public | Confidential |
| Redirect URIs | OAuth 콜백 URL (정확 일치, 다중 등록 가능) | http://localhost:4000/auth/callback |
| Webhook URL (선택) | 사용자 이벤트 endpoint | https://app.example.com/webhooks/logi |
Scopes 는 폼이 아닌 앱 상세 → Scopes 관리 에서 활성화.
발급 값
client_id—logi_...접두, 공개 안전client_secret— Confidential 만 발급, 저장 직후 1회만 노출. 분실 시 앱 상세 → Secret 재발급 (기존 즉시 무효화)LOGI_RP_HEALTH_SECRET—logi_rphs_접두.client_secret과 별개로 등록 직후 같은 페이지에서 1회만 노출됩니다 (CLI 는logi apps create응답에도 포함). RP 백엔드 env 에만 저장(클라이언트 번들/git 금지). 헬스 체크 HMAC 서명용 → RP Active Health Check. 분실 시 콘솔 rotate 또는logi apps rotate-secret <id>.
Client type
| Confidential (기본) | Public (PKCE-only) | |
|---|---|---|
| 대상 | 백엔드 보유 RP | 모바일·SPA 단독 |
| Secret | 발급 | 없음 |
| 인증 | HTTP Basic / form body | PKCE S256 강제 |
iOS / Android / Web 은 platform 별로 client_id 분리 등록.
⚠️ Warning: client_id 를 분리하면 사용자 식별은 반드시
canonical_sub로 logi 는 client_id 별로 다른 pairwisesub를 발급합니다. 따라서 같은 사용자가 platform(client_id)마다 다른sub을 받습니다. RP 가sub으로 사용자를 키잉하면 두 번째 platform 로그인 시 "이미 다른 계정과 연결"(AlreadyLinkedError) 로 실패할 수 있습니다.
사람 단위 식별은 client 전체에서 동일한 canonical_sub(= logi user.id, userinfo 가 항상 emit, merge 시에만 변경)로 하세요. → Sub 정책
등록 유형 분류 (Redirect URI 호스트 기준)
| 유형 | 조건 | 자동 승인 | 토큰 수명 |
|---|---|---|---|
| 개발(로컬) | localhost, 127.0.0.1 | ✅ 즉시 | 짧음 |
| 개발(인터넷) | *.staging.*, *.test.*, *.localhost | ✅ 즉시 | 짧음 |
| 프로덕션 | 실서비스 도메인 | ⏳ 관리자 검토 | 정상 |
다중 redirect_uri 등록 시 가장 엄격한 유형 으로 분류.
Redirect URI 규칙
- 정확 일치: byte-단위. query/fragment/trailing slash 차이 모두 거부
- Wildcard 미지원:
*.vercel.app등 불가 - HTTPS 강제:
localhost/127.0.0.1만http://허용
Production 승급
외부 도메인 redirect_uri 추가 시 status=pending. 외부 도메인 콜백은 승급 전까지 거부.
신청
- 앱 상세 → "Production 승급 신청"
- 폼:
- 사업자등록증 PDF (필수)
- 서비스 설명 (20자 이상)
- 기술 담당자 이메일
- logi 이용약관 + DPA 동의
- 제출 → 관리자 텔레그램 알림
결과
| 결과 | 의미 |
|---|---|
| ✅ 승인 | tier=production, status=approved. 외부 도메인 사용 가능 |
| ❌ 거절 | 메일·FAB 로 사유 회신 |
| ⏸ 보류 | changes_requested. 보완 후 재신청 |
로그인 방법 제한
앱 설정의 로그인 방법 제한 체크박스로 로그인 화면에 노출할 방법(Apple/Google/Kakao SSO · 이메일/비밀번호 · logi 앱)을 앱 단위로 제한할 수 있습니다.
- 체크박스를 모두 비워 두면(기본값) 전체 노출
- 체크한 방법만 노출되며, 숨겨진 SSO/QR/푸시 시작 경로는 서버에서도 차단됩니다
- 요청 단위로만 좁히고 싶다면 authorize URL 의
provider파라미터 사용
전체 동작·우선순위 규칙은 로그인 방법 제한 문서를 참고하세요.
유형 전환
- 로컬 → 인터넷:
*.staging.*redirect_uri 추가 시 자동 전환, 신청 불필요 - 인터넷 → 프로덕션: 외부 도메인 추가 →
pending. 승급 신청 필요 - production 승급 후 redirect_uri 변경 시 재심사 가능
수정 / 삭제
- 수정: 앱 상세 → 편집. 이름·redirect_uri·webhook·allowed_scopes 변경 가능. 외부 도메인 추가 시 재심사 트리거
- 삭제: 앱 상세 하단 삭제.
client_id즉시 거부, 발급 토큰 revoke, 복구 불가
콜백 path rename (브랜드 통합, 라우트 정비)
SP 측에서 callback path 자체를 바꿀 때 (예: /auth/1pass/callback → /auth/logi/callback) 는 무중단 cutover 가 필수입니다. 한쪽만 배포하면 invalid_request: redirect_uri not registered 가 즉시 발생합니다.
권장 순서:
- IdP 먼저: 신규 path 를 redirect_uris 에 추가 (이전 path 도 유지, 배열에 둘 다)
- SP 배포: 코드에서 신규 path 사용 시작 — in-flight 세션은 이전 path 로 콜백 계속
- 유예 기간: 이전 path 로 도착하는 트래픽 0 됐는지 IdP 로그로 확인 (보통 7일+)
- 이전 path 제거: redirect_uris 에서 삭제
배포 직전 검증은 oauth/troubleshooting.md 회귀 방지 의 curl preflight 참고.
FAQ
Vercel preview URL: 와일드카드 미지원. preview 전용 sandbox 앱 분리 권장.
client_secret 재확인: 불가. Secret 재발급 으로 새 값 (기존 무효화).
사업자등록증 없음: 개인 사업자 가능. 둘 다 없으면 sandbox tier 만.
문의
개발자 센터 우하단 💬 FAB → 관리자 텔레그램.
LLM 친화 버전
curl https://docs.1pass.dev/llms/guide/registering-apps.md전체 번들: https://docs.1pass.dev/llms-full.txt