인증과 키
Publishable Key, Secret Key, CORS, 사용자 접근을 올바른 신뢰 경계에서 사용합니다.
프로젝트, 서버, 외부 업체, AI 에이전트를 워크스페이스에 연결하기 전에 이 페이지를 사용합니다.
키 종류
| 자격 증명 | 사용처 | 넣지 말아야 할 곳 |
|---|---|---|
| Publishable Key | 공개 읽기와 capability/customer 인증된 operation; 신뢰할 수 있는 shell의 Agent CLI 0.20.1에서는 Secret Key와 함께 사용 | 권한 쓰기 |
| Secret Key | 서버 측 SDK 쓰기, 신뢰할 수 있는 shell의 Agent CLI | 브라우저 코드, 명령 인자, 로그, 스크린샷, 커밋 |
| 사용자 접근 | 사람 기준 Console, OAuth, Human CLI 작업 | agent 공유 자동화 |
| MCP OAuth 접근 | 읽기 전용 도구 3개를 통한 hosted·shell 없는 discovery | collection CRUD 또는 commerce workflow |
Greenfield app creator는 사용자와 애플리케이션 identity를 분리합니다. 브라우저
승인은 자격 증명 없는 스캐폴드의 설치가 끝난 뒤에만 개발 목적 sk01_ 하나를
발급할 수 있으며, Human CLI의 pat01_는 앱 환경 입력으로 사용할 수 없습니다.
Production service credential은 scaffolder option이 아니라 명시적인 Console
작업으로 발급합니다.
관리자 2단계 인증
플랫폼이 tenant-admin MFA 정책을 활성화하면, 어느 워크스페이스에서든 관리자 역할이 있는 계정은 계정 전체에 2단계 인증이 필요합니다. 워크스페이스의 상태나 현재 선택과 무관합니다. 아직 등록하지 않았다면 다음 비밀번호 또는 Google 로그인에서 인증 앱을 등록하고, 한 번 표시되는 복구 코드를 안전하게 저장한 뒤 다시 로그인하세요. 필수 계정은 2단계 인증을 직접 해제할 수 없습니다. 관리자 승격 시 재로그인이 필요합니다. Onboarding 중 승격되면 안내에 따라 로그인하고 MFA 등록을 마친 뒤 기존 API 키 단계로 돌아오세요. 미등록 계정의 비밀번호 재설정은 비밀번호만 변경하고 등록을 위한 로그인 화면으로 안내합니다. 이미 등록한 계정은 비밀번호 재설정에도 MFA가 필요합니다.
활성화와 관리자 승격 시 MFA 검증 이력 없이 발급된 PAT는 회수됩니다. MFA 검증 후 발급한 PAT와 서비스 키는 유지됩니다. Super-admin 승격은 기존처럼 모든 PAT를 회수합니다. 자동화에는 사람의 PAT 대신 전용 서비스 키를 사용하세요.
인증 앱과 복구 코드를 모두 잃었다면 플랫폼 지원에 수동 복구를 요청하세요. 다른 super-admin이 영상 통화 또는 대면으로 본인을 확인한 뒤 일회용 등록 승인 코드를 전달합니다. 새 로그인 증명과 새 인증 앱의 코드로 다시 등록해야 하며, 승인 코드를 이메일, URL 또는 이슈에 붙이지 마세요.
서비스 키 발급 확인
운영자 MFA 강제화가 활성화된 설치에서는 MFA 등록 계정 또는 필수 대상이 서비스 키를 생성·재발급할 때 인증 앱의 새 6자리 TOTP를 입력합니다. 온보딩과 브라우저 앱 승인에도 적용하며 복구 코드로는 발급을 승인할 수 없습니다. 필수 대상인데 미등록이면 MFA 등록을 먼저 완료해야 합니다. 비활성 설치의 발급은 기존과 같습니다. 비필수·미등록 계정의 기존 발급은 필수 역할 정책 적용 전의 호환 동작이며, tenant-admin 전체 필수 정책 활성화 뒤에는 모든 tenant-admin 발급자에게 적용됩니다.
운영자 세션의 HTTP 요청은 code를 받을 수 있고 필요 여부는 Console이 판정합니다. 공개 SDK는 발급된 키를 사용하며 키 발급 API를 노출하지 않습니다. 키 폐기에는 작업 TOTP가 필요하지 않습니다.
CORS와 Origin
- 워크스페이스 데이터를 읽어야 하는 브라우저 origin만 추가합니다.
- staging, preview, production origin은 별도 승인으로 봅니다.
- 도메인 변경이나 외부 업체 종료 후에는 오래된 origin을 제거합니다.
서버 경계
- 권한 작업은 신뢰할 수 있는 서버 route, server action, worker, backend service 안에 둡니다.
- Secret Key 값은 체크인된 코드가 아니라 환경 저장소에서 불러옵니다.
- Agent CLI 자동화는
SOFTWARE_PUBLISHABLE_KEY와SOFTWARE_SECRET_KEY를 우선 사용하고 secret을 명령 인자로 넘기지 않습니다. - 운영자가 바뀌면 Secret Key 소유권을 회전합니다.
자격 증명이 불명확하면 구현을 멈추고 연동과 키 관리로 돌아갑니다.
고객 세션
Customer access/refresh token은 최종 사용자 identity이며 Console 운영자나 서버 자격 증명이 아닙니다. 새 앱은 enabled 등록 client, exact origin/redirect, state 검사, trusted server token 보관으로 hosted OAuth/PKCE를 사용합니다. token은 HttpOnly 쿠키나 server-owned 세션에 두고 브라우저 JavaScript·localStorage에는 두지 마세요. 브라우저 API origin과 hosted OAuth origin/redirect는 별도 등록입니다. me()로 현재 고객 조회, 회전과 로그아웃은 Customers 가이드, 메서드 경계는 Customers SDK를 따릅니다.
Publishable Key는 워크스페이스를 결정하고, 공개 읽기와 명시적으로 capability 또는 고객 인증으로 허가된 작업만 허용합니다. 임의 쓰기를 허용하지 않습니다. Secret Key와 pat01_ 운영자 credential은 trusted 환경에 두며 PAT를 앱 service key로 사용하지 않습니다.
선택적 핸들 비밀번호 로그인
워크스페이스 관리자는 기존 Admin Panel 고객 인증 설정에서 customerAuth.handleLoginEnabled를 켤 수 있습니다. 기본값은 꺼짐입니다. 별도 비공개 로그인 ID가 아닌 현재 계정 핸들을 쓰며, 핸들 migration과 서버 배포가 끝난 뒤 활성화합니다.
기존 이메일·비밀번호 요청은 유지됩니다. 활성화된 워크스페이스에서는 직접 client.customer.auth.login({ handle, password })에 이메일 대신 핸들 하나를 보냅니다. 둘 다 보내거나 둘 다 없으면 검증 오류입니다. CustomerLoginData의 기존 이메일 인터페이스는 유지되고 CustomerPasswordLoginData가 핸들 분기를 추가합니다. 저장된 이메일과 로컬 비밀번호가 있는 계정만 핸들 로그인을 사용할 수 있습니다. 설정을 꺼도 이메일 로그인, 공개 핸들, 기존 세션은 유지됩니다.
신규 스토어는 hosted OAuth를 권장합니다. hosted 서버의 비밀번호 endpoint도 핸들 입력을 받지만 hosted 로그인 화면에는 아직 핸들 입력이 없습니다. 비밀번호 없는 이메일 코드와 비밀번호 재설정은 이메일을 계속 사용합니다. 변경하거나 지운 이전 핸들은 로그인 별칭으로 남지 않습니다. 이메일과 핸들에는 같은 로그인 오류·잠금 규칙이 적용됩니다.