Quickstart — 한 번에 서비스 붙이기

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

📍 Jump-to Index

L32-L96: ## 🚀 5분 만에 로그인 세팅하기
- L77-L96: ### 등록을 마쳤다면 — 통합 코드까지 시키는 프롬프트
L97-L188: ## 수동으로 직접 하려면
- L104-L139: ### 1. 로그인 (계정이 없으면 먼저 가입)
- L140-L155: ### 2. RP 등록
- L156-L177: ### 3. secret env 주입
- L178-L188: ### 4. 검증
L189-L197: ## 이렇게 시켜보세요
L198-L205: ## 다음 단계
L206-L324: ## 수동 통합 (curl)
- L213-L216: ### 사전 준비
- L217-L227: ### 환경 변수
- L228-L240: ### PKCE 페어 생성
- L241-L258: ### Authorization Code 받기
- L259-L298: ### Token 교환
- L299-L318: ### 신원 조회 — 두 가지 방법
- L319-L324: ### 수동 통합 트러블슈팅

Quickstart — 한 번에 서비스 붙이기

이 페이지 하나로 logi 로그인을 자기 서비스(RP)에 붙입니다.

🚀 5분 만에 로그인 세팅하기

💡 Tip: 계정이 아직 없다면 logi login 은 로그인입니다(가입 아님). logi 계정이 없으면 먼저 1pass 앱 또는 소셜 로그인(Apple/Google) 으로 가입하세요 — 소셜은 첫 로그인 시 자동 생성됩니다. (앱 설치: install)

해야 할 일은 3가지 — 나머지는 아래 프롬프트가 알아서 합니다.

아래 프롬프트를 복사해 Claude Code · Cursor · Codex 에 붙여넣기 — <...> 부분만 본인 값으로 치환.
폰에서 로그인 한 번 승인 — 이메일로 가입했다면 메일로 온 6자리 코드도 전달 (Google · Apple 가입은 자동).
받은 비밀값을 배포 환경변수에 주입 — 코드·git 엔 넣지 않기 (딱 한 번만 노출됩니다).

끝나면 로그인 연동에 필요한 앱 ID 1개 + 비밀값 2개 + 환경변수 블록을 받습니다 — 남은 건 프레임워크별 가이드대로 버튼과 콜백만 붙이면 됩니다.

text

logi CLI 가 없으면 먼저 설치해줘: brew install dcode-co/logi/logi  (또는 gem install logi-cli)

그다음 logi manual 을 실행해 매뉴얼을 컨텍스트에 로드하고, logi CLI 로 개발자 등록 + RP 등록을 끝까지 진행해줘. (manual 명령이 없는 구버전 CLI 면 대신 https://docs.1pass.dev/llms/guide/cli-rp-registration.md 를 읽어줘.)

1. logi login 으로 로그인 (브라우저 OAuth — 내가 폰에서 1회 승인할게). (계정이 없으면 폰의 1pass 앱 또는 소셜 로그인으로 먼저 가입 — SSO 는 자동 생성.)
2. logi developer register --email <dev@example.com> --org "<My Company>" 로 개발자 권한 승격.
3. logi developer status 로 identity_verified_level 확인 — unverified 면 logi developer verify-email 실행하고, 이메일로 온 6자리 코드를 나한테 물어봐서 입력해줘. (SSO 가입이면 이미 email_verified 라 이 단계는 skip.)
4. logi apps create 로 RP 등록:
   - --name "<My App>"
   - --redirect-uri 에 콜백 URL 을 byte 단위로 정확히 한 개 넣어 생성한 뒤, 추가 콜백(local / staging / prod / 모바일 scheme)이 더 있으면 logi apps add-redirect <id> <uri> 로 하나씩 등록.
   - --scope openid profile:basic email   (유효 scope 이름만 — profile 단독 X, profile:basic O)
   - 시크릿을 숨길 수 있는 백엔드가 있으면 --client-type confidential, 모바일/SPA 단독이면 --client-type public. (등록 후 변경 불가니 신중히.)
5. create 응답의 client_id / client_secret / rp_health_secret 과 env 블록을 나한테 보여줘. secret 은 1회만 노출되니 절대 코드/git 에 커밋하지 말고, 내가 배포 플랫폼 env 에 넣게 안내만 해줘.
6. logi apps verify <id> 로 등록 상태를 검증하고, 프로덕션 도메인이라 pending 이면 admin 승급이 필요하다고 알려줘.

redirect_uri 미스매치가 OAuth #1 사고이니 5번을 특히 꼼꼼히. 진행 중 막히면 https://docs.1pass.dev/llms.txt 의 인덱스에서 해당 토픽을 찾아 참고해줘.

📖 Details: 이 프롬프트가 정확히 무엇을 하는지 — 펼쳐보기 무엇이 되나 — 사용자는 logi 앱에서 한 번 승인으로 로그인하고, 내 서비스 쪽은 프레임워크별 가이드대로 콜백에서 코드를 받아 토큰 교환만 붙이면 됩니다. 비밀번호 저장·소셜 연동·토큰·보안은 logi 가 맡습니다.

AI 가 대신 하는 일 — CLI 설치 확인부터 logi manual(자기설명서 자동 로드, 구버전 폴백: 등록 한방 가이드 LLM 판)로 호스트(api.1pass.dev)·scope(openid profile:basic email) 같은 사실을 맞추고 → 개발자 등록 → 앱 등록 → 등록 검증까지. 콜백 URL·client type 처럼 정할 게 있으면 AI 가 묻고 사람이 확인합니다.

받는 값 3개 — client_id(공개해도 안전) + client_secret·rp_health_secret(서버 전용, 한 번만 노출). 모바일·SPA(public client)면 client_secret 없이 발급됩니다.

💡 Tip: 전체 단계별 설명 + 검증 체크리스트 이 프롬프트의 단일 출처는 CLI 단계별 RP 등록 (한방 가이드) 입니다. 각 단계 상세 설명, 자주 막히는 곳, 거짓 "완료" 보고를 막는 검증 체크리스트가 거기 있습니다.

⚠️ Warning: 프롬프트에 내부 인프라 값을 넣지 마세요 위 프롬프트는 공개 CLI 명령과 공개 docs URL 만 씁니다. 본인의 secret 값 · 배포 플랫폼 토큰 · 서버 접속 정보는 프롬프트에 넣지 말고, AI 가 명령을 만들면 secret 은 본인이 직접 env 보관처에 주입하세요.

등록을 마쳤다면 — 통합 코드까지 시키는 프롬프트

위 등록 프롬프트로 client_id 를 받았다면, 이번엔 아래를 붙여넣으세요. 에이전트가 트랙 분기(mobile/web/api) + F1-F8 함정 + Anti-patterns 가 정리된 Quickstart for Agents (RP 통합 런북) 을 읽고 통합 코드를 작성합니다.

text

https://docs.1pass.dev/llms/guide/agent-quickstart.md 를 가장 먼저 읽고, 이 프로젝트에 logi 로그인을 붙여줘.

- client_id: <등록 때 받은 값>   (공개값)
- issuer: https://api.1pass.dev
- redirect_uri: 등록한 값과 byte 단위로 동일하게 사용
- client_secret / rp_health_secret 은 배포 env 에 이미 넣어뒀어 — 코드·git 에 쓰지 말고 env 참조로만 사용해줘.

트랙(mobile / web / api)을 먼저 판정하고, 해당 트랙의 통합 가이드 한 개만 적용해줘.

💡 Tip: 이 프롬프트에도 secret 은 넣지 않습니다 client_id 는 공개값이라 프롬프트에 넣어도 안전합니다. client_secret / rp_health_secret 은 위 3번(배포 env 주입)을 마친 상태가 이 프롬프트의 전제입니다.

수동으로 직접 하려면

CLI 명령을 손으로 직접 칠 거라면 아래 순서를 따르세요. 관리형 IdP 호스트는 https://api.1pass.dev 이며, 자체 호스팅은 self-hosting 입니다.

💡 Tip: OAuth canonical host issuer 와 discovery 는 https://api.1pass.dev 에 고정입니다: /.well-known/openid-configuration·/.well-known/jwks.json 는 여기에만 있고 start.1pass.dev 에선 404, id_token 의 iss 도 https://api.1pass.dev (브랜드명 "logi" 아님). start.1pass.dev 는 콘솔 전용입니다. 일부 엔드포인트는 두 호스트에서 응답하지만, RP 는 모든 엔드포인트를 api.1pass.dev 로 통일하세요 (issuer 와 일치).

1. 로그인 (계정이 없으면 먼저 가입)

logi CLI 한 줄로 설치합니다.

bash

brew install dcode-co/logi/logi
# 또는
gem install logi-cli

설치 상세 / 트러블슈팅: logi CLI 설치.

계정이 없으면 1pass 앱 또는 SSO 로 먼저 가입하세요. logi login 은 기존 계정 로그인입니다.

로그인 — 브라우저가 열리고 폰에서 1회 승인하면 끝납니다. 서버/SSH/도커처럼 브라우저가 없으면 logi login --code (device flow).

bash

logi login

개발자 권한으로 승격합니다 (RP 등록 게이트 통과에 필요).

bash

logi developer register --email dev@example.com --org "My Company"

이메일 검증 — SSO(Google/Apple) 가입이면 자동 검증되어 이 단계를 건너뜁니다. 이메일/비밀번호 가입자만 코드를 입력합니다.

bash

logi developer status          # identity_verified_level 확인
logi developer verify-email    # unverified 면 — 이메일로 받은 6자리 코드 입력

ℹ️ Note: SSO 가입자는 자동 검증 Google / Apple 로그인 계정은 IdP 가 이메일을 이미 검증했으므로 identity_verified_level 이 자동으로 email_verified 입니다. 명령어 상세: 개발자 등록.

2. RP 등록

bash

logi apps create \
  --name "My App" \
  --redirect-uri https://app.example.com/auth/logi/callback \
  --scope openid profile:basic email \
  --client-type confidential

redirect_uri 는 byte 단위 정확 일치 — --redirect-uri 는 생성 시 한 개 만 받습니다. local / staging / prod / 모바일 scheme 등 여러 개가 필요하면 하나로 생성한 뒤 logi apps add-redirect <id> <uri> 로 추가하세요 (redirect URI 규칙).
모바일/SPA 등 시크릿을 못 숨기는 RP 는 --client-type public (public vs confidential). 등록 후 변경 불가.
BCL 을 쓸 거면 --backchannel-logout-uri (Back-Channel Logout), 모바일 RP 의 백엔드 헬스 호스트는 --health-url, 헬스 체크를 끌 거면 --no-health-check (RP Active Health Check).

전체 옵션: 앱 관리 명령어. 등록 정책(위험 평가 · production 승급 · rate limit): 앱 등록 가이드.

3. secret env 주입

logi apps create 출력에서 3개 값 이 이 순간에만 평문으로 나옵니다.

client_id:        logi_...        ← 공개 안전
client_secret:    logi_secret_... ← confidential 만, 1회
rp_health_secret: logi_rphs_...   ← 1회, 서버 env 전용

함께 출력되는 env 블록을 배포 플랫폼(Render / Vercel / Fly / Heroku / self-hosted)의 환경 변수에 넣습니다.

bash

LOGI_API_URL=https://api.1pass.dev
LOGI_CLIENT_ID=logi_...
LOGI_CLIENT_SECRET=logi_secret_...
LOGI_RP_HEALTH_SECRET=logi_rphs_...

🚨 Danger: secret 은 서버 env 전용 LOGI_CLIENT_SECRET 과 LOGI_RP_HEALTH_SECRET 은 클라이언트 코드(모바일 바이너리 / SPA 번들 / 공개 git)에 절대 넣지 마세요. client_secret 과 rp_health_secret 은 create 응답에서만 평문으로 나오고 GET(list/show)엔 없습니다 — 놓치면 secret 회전이 필요합니다. Public client 면 애초에 client_secret 이 없습니다.

4. 검증

bash

logi apps verify <id>

tier / status / rp_health_status / health_check_enabled 가 표시됩니다. localhost redirect 만 있으면 자동 승인(approved)되고, 프로덕션 도메인이 포함되면 pending 으로 admin 검토 가 필요합니다. RP 헬스 엔드포인트가 실제로 응답하는지 직접 확인은 자가 진단 curl 참고.

💡 Tip: 거짓 "완료" 방지 — 검증 체크리스트 CLI 설치 · 로그인 · developer 권한 · 이메일 검증 · RP 생성 · 3개 secret 확보 · env 주입 · 검증 green 을 한 항목씩 확인하는 체크리스트는 CLI 한방 가이드 · 검증 체크리스트 에 있습니다.

이렇게 시켜보세요

등록이 끝난 뒤 에이전트에게 그대로 붙여넣을 수 있는 후속 요청 예시입니다 — client_id 만 본인 값으로 바꾸세요.

"이 Next.js 앱에 logi 로그인 붙여줘. client_id 는 logi_... 이고, secret 은 배포 env 에 있어." → Next.js 통합
"Rails 콜백에서 code 교환 + id_token 검증까지 붙여줘." → Rails 8 통합
"Flutter 앱에 logi 로그인 넣고, custom scheme 콜백도 logi apps add-redirect 로 등록해줘." → Flutter 통합
"back-channel logout 받는 엔드포인트 만들고 logout_token 검증까지 해줘." → Back-Channel Logout

다음 단계

트랙별 코드 드롭인: 웹 Next.js · Rails 8 · Express / 모바일 iOS · Android · Flutter · React Native
버튼 컴포넌트 · Refresh rotation · Webhook · Account Merge · Security
에이전트 런북: Quickstart for Agents · CLI 한방 가이드: cli-rp-registration

수동 통합 (curl)

CLI 없이 OAuth 끝점을 직접 호출해 붙이는 경로입니다. 위의 CLI 흐름으로 RP 를 등록(또는 콘솔 에서 등록)한 뒤, client_id / client_secret / redirect_uri 만 준비되면 됩니다.

💡 Tip: 끝점 발견 모든 끝점은 https://api.1pass.dev/.well-known/openid-configuration 에서 발견됩니다. start.1pass.dev 는 discovery 404 이니 쓰지 마세요.

사전 준비

bash, curl, openssl, python3.

환경 변수

bash

export LOGI="https://api.1pass.dev"
export CLIENT_ID="logi_..."
export CLIENT_SECRET="..."         # Public client 면 생략
export REDIRECT="http://localhost:4000/auth/callback"

scope 는 openid profile:basic email 처럼 유효 이름만 씁니다 — bare profile 은 거부됩니다. id_token 을 페이로드에서 직접 읽는 패턴은 openid scope 가 필수이고, 없으면 token 응답에 id_token 이 빠집니다 (Scope 레퍼런스).

PKCE 페어 생성

bash

VERIFIER=$(openssl rand -hex 32)

CHALLENGE=$(printf '%s' "$VERIFIER" \
  | openssl dgst -sha256 -binary \
  | python3 -c 'import sys,base64; print(base64.urlsafe_b64encode(sys.stdin.buffer.read()).rstrip(b"=").decode())')

echo "verifier  = $VERIFIER"
echo "challenge = $CHALLENGE"

Authorization Code 받기

bash

open "$LOGI/oauth/authorize?\
client_id=$CLIENT_ID&\
redirect_uri=$REDIRECT&\
response_type=code&\
scope=openid+profile:basic+email&\
state=random_xyz&\
code_challenge=$CHALLENGE&\
code_challenge_method=S256"

→ http://localhost:4000/auth/callback?code=...&state=random_xyz. code 값 복사.

💡 Tip: 로그인 화면에 특정 방법만 노출하기 사내에서 Google Workspace 만 쓰는 등 특정 로그인 방법만 보여주고 싶다면 authorize URL 에 provider 파라미터를 추가하세요 (예: &provider=google → "Google로 계속" 버튼만 노출). 자세한 동작은 로그인 방법 제한 참조.

Token 교환

bash

CODE="복사한_code"

curl -s -X POST "$LOGI/oauth/token" \
  -d grant_type=authorization_code \
  -d code=$CODE \
  -d redirect_uri=$REDIRECT \
  -d code_verifier=$VERIFIER \
  -d client_id=$CLIENT_ID \
  -d client_secret=$CLIENT_SECRET

Public client: -d client_secret=... 줄 제거. 보내면 invalid_client 거절.

bash

curl -s -X POST "$LOGI/oauth/token" \
  -d grant_type=authorization_code \
  -d code=$CODE \
  -d redirect_uri=$REDIRECT \
  -d code_verifier=$VERIFIER \
  -d client_id=$CLIENT_ID

응답:

json

{
  "access_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6Ii4uLiJ9...",
  "token_type": "Bearer",
  "expires_in": 900,
  "refresh_token": "DWxB...",
  "id_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6Ii4uLiJ9...",
  "scope": "openid profile:basic email"
}

id_token 은 openid scope 를 요청했을 때만 포함됩니다.

신원 조회 — 두 가지 방법

id_token 에서 sub 읽기 (서명 재검증 불요) — /oauth/token 응답을 TLS 로 직접 받았다면 id_token 페이로드의 sub 를 바로 신뢰할 수 있습니다. 단 id_token 에는 sub 등 OIDC 표준 claim 만 있고 email·name 은 없습니다.

bash

echo "$ID_TOKEN" | cut -d. -f2 | base64 -d 2>/dev/null | python3 -m json.tool
# → {"iss":"https://api.1pass.dev","sub":"1","aud":"logi_...","exp":...,"iat":...,"at_hash":"..."}

💡 Tip: 토큰 엔드포인트에서 직접 받았다면 서명 재검증은 선택 같은 백엔드 요청에서 /oauth/token 으로부터 TLS 로 직접 수신한 id_token 은 페이로드를 신뢰해도 됩니다(OIDC §3.1.3.7 #6 예외). 서명(JWKS) 검증은 id_token 이 신뢰할 수 없는 경로(front-channel, 저장 후 재사용, 중계)로 들어올 때만 필수입니다. iss 는 리터럴 "https://api.1pass.dev", aud 는 CLIENT_ID 와 둘 다 일치해야 합니다. → JWKS 검증

userinfo 로 프로필(email·name) 받기 — email·name 등 프로필은 id_token 에 없으므로 access_token 으로 userinfo 를 호출합니다.

bash

ACCESS_TOKEN="위_응답의_access_token"
curl -s -H "Authorization: Bearer $ACCESS_TOKEN" "$LOGI/oauth/userinfo"
# → {"sub":"1","nickname":"길동","name":"홍길동","email":"user@example.com","email_verified":true}

수동 통합 트러블슈팅

invalid_client: Public client 가 client_secret 전송 — 줄 제거.
PKCE: S256 필수, plain 거절. redirect_uri 는 https / 127.0.0.1 / localhost / custom-scheme 만 허용하고 등록값과 byte 단위로 일치해야 합니다.
더 자세히: OAuth 트러블슈팅.

Quickstart — 한 번에 서비스 붙이기 ​

📍 Jump-to Index ​

Quickstart — 한 번에 서비스 붙이기 ​

🚀 5분 만에 로그인 세팅하기 ​

등록을 마쳤다면 — 통합 코드까지 시키는 프롬프트 ​

수동으로 직접 하려면 ​

1. 로그인 (계정이 없으면 먼저 가입) ​

2. RP 등록 ​

3. secret env 주입 ​

4. 검증 ​

이렇게 시켜보세요 ​

다음 단계 ​

수동 통합 (curl) ​

사전 준비 ​

환경 변수 ​

PKCE 페어 생성 ​

Authorization Code 받기 ​

Token 교환 ​

신원 조회 — 두 가지 방법 ​

수동 통합 트러블슈팅 ​

Quickstart — 한 번에 서비스 붙이기

📍 Jump-to Index

Quickstart — 한 번에 서비스 붙이기

🚀 5분 만에 로그인 세팅하기

등록을 마쳤다면 — 통합 코드까지 시키는 프롬프트

수동으로 직접 하려면

1. 로그인 (계정이 없으면 먼저 가입)

2. RP 등록

3. secret env 주입

4. 검증

이렇게 시켜보세요

다음 단계

수동 통합 (curl)

사전 준비

환경 변수

PKCE 페어 생성

Authorization Code 받기

Token 교환

신원 조회 — 두 가지 방법

수동 통합 트러블슈팅