배포

프런트엔드는 프레임워크와 호스팅 제공자의 안내에 따라 배포합니다. 빌드 옵션의 모든 경로에 아래 01.software 설정을 적용하세요. 환경 변수 예시는 Next.js 기준이며, 다른 실행 환경에서는 해당 환경의 규칙을 따릅니다.

공통 배포 절차

1. 배포용 자격 증명 설정하기

배포한 앱이 접근할 환경의 Publishable Key를 사용하세요. 별도 운영용 Secret Key는 권한 있는 서버 작업에만 필요합니다. 브라우저 전용 앱과 공개 상품 조회에는 필요하지 않습니다. Community Forum 스타터도 앱 측 Secret Key 없이 Publishable Key와 고객 JWT를 사용합니다.

로컬 .env.local을 호스트로 복사하지 마세요. 필요한 경우 Console에서 운영용 키를 발급하고, 한 번만 표시되는 값을 호스트의 서버 전용 시크릿 설정에 저장하세요. 잃어버렸다면 교체 키를 발급합니다.

비밀값을 NEXT_PUBLIC_, VITE_, REACT_APP_ 변수, 브라우저 코드, 명령 인자, URL, 커밋에 넣지 마세요. 공개 환경 변수 접두사를 피하더라도 앱 코드가 응답이나 로그로 비밀값을 노출할 수 있으므로 주의해야 합니다. Human CLI의 pat01_는 애플리케이션 키가 아닙니다. 자세한 내용은 인증을 참고하세요.

최초 배포라면 여기서 호스트 설정을 마친 뒤 4단계에서 배포하세요. 이미 배포된 앱의 키를 교체한다면 교체 키 발급, 호스트 설정 변경, 배포 또는 재시작, 호출 확인을 순서대로 진행하고 교체 키의 동작을 확인한 뒤 이전 키를 철회하세요.

2. 브라우저에서 호출한다면 origin 허용하기

Console의 워크스페이스 레코드에서 브라우저 API origin에 배포한 origin을 추가하세요.

https://your-app.example.com

정확한 origin과 한 단계 와일드카드 서브도메인을 받습니다.

https://example.com          정확히 일치
https://*.example.com        서브도메인 한 단계
http://localhost:3000        로컬 개발

프리뷰 origin도 포함하세요. 허용 목록이 비어 있으면 모든 브라우저 호출이 차단됩니다. 브라우저 Origin 없이 실행된 서버 호출의 성공으로는 이 설정을 확인할 수 없습니다. 자세한 설정은 연동과 키를 참고하세요.

3. 호스티드 고객 OAuth를 사용한다면 등록하기

앱의 실제 인증 구성을 확인하세요. 호스티드 고객 OAuth에는 해당 customer-oauth-clients 레코드의 별도 설정이 필요합니다.

• allowedOrigins: 정확히 정규화된 브라우저 Origin이 하나 이상 필요합니다. Origin 헤더가 있는 token·refresh 요청에서 검사합니다. 이 헤더가 없는 서버·비브라우저 요청은 허용합니다.
• allowedRedirectUris: 정확한 callback URI가 하나 이상 필요합니다.
• allowedLogoutUris: 앱이 사용하는 모든 로그아웃 후 URI를 등록합니다.

이 목록들은 서로를 대체하지 않으며 워크스페이스의 API origin 허용 목록도 대체하지 않습니다. Authorize page는 allowedOrigins 대신 redirect URI와 scope를 검사합니다. 미등록 callback URI는 거부됩니다.

redirect_uri is not registered for this client

앱의 실제 경로를 사용하세요. 다음은 Next.js 고객 OAuth 예시입니다.

allowedOrigins: https://your-app.example.com
allowedRedirectUris: https://your-app.example.com/api/auth/customer/callback
allowedLogoutUris: https://your-app.example.com/account
allowedLogoutUris: https://your-app.example.com/

OAuth 설정에는 와일드카드나 localhost를 포함한 loopback 호스트 없이 정규화된 HTTPS 주소를 사용해야 합니다. 프리뷰마다 origin, callback, 로그아웃 URI를 각각 등록하세요. 소셜 제공자와 인증의 자세한 설정은 인증에서 확인하세요.

신규 고객 연동에는 호스티드 OAuth/PKCE 흐름을 사용하세요. 일회용 state와 PKCE verifier는 신뢰할 수 있는 서버 세션에 보관하고, callback에서 예상 state를 검사한 뒤 해당 verifier로 코드를 교환합니다. Access·refresh token은 SDK 영속 저장을 끄고(persist: false) HttpOnly 쿠키나 서버 세션에 보관하세요. 브라우저에서 읽을 수 있는 저장소, URL, 로그에는 두지 마세요. 고객 정보는 me()로 확인합니다. SDK가 ID token을 검증해 주지는 않습니다.

직접 login을 쓰는 앱(Community Forum 스타터 포함)은 legacy 호환입니다. Community Forum 스타터의 로그아웃은 앱의 HttpOnly 세션 쿠키만 지우며, SDK 로그아웃을 호출하거나 서버에서 token을 철회하지 않습니다. 앱이 direct logoutAsync()를 호출한다면 Publishable Key가 속한 워크스페이스의 legacy-direct refresh family만 철회하며, 이미 발급한 access JWT를 즉시 철회하지 않습니다. 서버에서 실패해도 로컬 token 쌍을 지우고 실패를 보고합니다. 동기 logout()은 로컬 상태만 지웁니다. 어느 쪽도 호스티드 로그아웃을 대체하지 않습니다.

4. 배포하고 해당하는 호출 각각 확인하기

프레임워크와 호스트의 절차로 배포하세요. Vercel은 Next.js 호스트의 한 선택지이며 필수는 아닙니다. 앱에 필요한 공개 값과 서버 전용 시크릿만 설정합니다.

빠른 시작 페이지는 동적 렌더링을 명시하므로 상품 조회는 next build 중이 아니라 페이지 요청마다 실행됩니다. Next.js 앱을 빌드할 때 NEXT_PUBLIC_SOFTWARE_PUBLISHABLE_KEY를 설정하고, 바꿨다면 다시 빌드하세요. 빌드 성공만으로 그 키나 API 접근을 확인할 수는 없습니다.

• 배포한 페이지를 열고 실제 API 결과를 확인하세요. 해당하는 경우 데이터가 없는 정상 결과도 포함합니다.
• Secret Key가 필요한 서버 작업은 배포한 키로 직접 확인하세요. 공개 상품 개수만으로는 Secret Key를 사용하는 작업을 확인할 수 없습니다.
• 브라우저 호출이 있다면 실제 브라우저 요청이나 아래 origin 확인 명령으로 검사하세요. 서버 렌더링만으로는 브라우저 접근을 확인할 수 없습니다.
• 호스티드 고객 로그인은 등록한 client·origin·redirect, callback의 state·PKCE 거부, HttpOnly 세션, me() 결과를 확인하세요. Refresh 회전과 재사용 거부 후 호스티드 로그아웃을 확인합니다. 호스티드 로그아웃은 refresh family를 철회하고 활성 access token ID와 로그아웃 fence 이전의 refresh family를 정리합니다. 서버가 중단된 로그아웃을 복구할 때는 해당 intent의 fence 이후 발급된 family를 보존하지만, 앱이 새로 보낸 로그아웃 요청은 새 fence로 다시 정리합니다. 앱 쿠키와 캐시는 별도로 지우세요. 서버 로그아웃이 실패하면 철회 완료가 아닙니다. Token·고객 정보 응답은 no-store여야 합니다. 앱에서 direct logoutAsync()를 호출한다면 legacy refresh family 철회를 별도로 검사하세요. Community Forum 스타터는 쿠키 삭제를 따로 확인하고 이를 서버 token 철회로 해석하지 마세요.
• 브라우저에 전달되는 빌드 산출물에 비밀값이 없는지 살펴보세요. 페이지가 동작한다고 비밀값이 안전하다는 뜻은 아닙니다.

이 확인만으로 출시 준비 상태가 보장되지는 않습니다.

브라우저 접근 문제 해결

origin이 거부되면 API는 403과 origin_not_allowed를 반환합니다. 다만 Access-Control-Allow-Origin이 없어 브라우저가 JavaScript에 응답을 전달하지 않고 일반 CORS 오류를 표시합니다. 키가 없는 일반 preflight는 뒤의 실제 요청이 차단되어도 200과 Access-Control-Allow-Origin: *를 반환할 수 있습니다.

아래 진단 명령은 Publishable Key를 넣어 선택한 워크스페이스의 origin 허용 목록을 확인합니다. 일반 브라우저 preflight와는 다릅니다.

curl -i -X OPTIONS https://api.01.software/api/products \
  -H "X-Publishable-Key: pk01_..." \
  -H "Origin: https://your-app.example.com" \
  -H "Access-Control-Request-Method: GET"

키가 노출됐다면 노출 원인을 제거하고 교체하세요. 자격 증명 취급은 인증을 참고하세요.

연동과 키, 인증, 출시 준비 점검으로 이어가세요.