인증 설정

Connect Base는 3개 계층의 인증을 사용합니다. 헷갈리지 않도록 먼저 전체 그림을 보세요.

3-Layer 인증 모델

┌─────────────────────────────────────────────────────────────┐
│  ① 콘솔 계정 (Console Account)                              │
│     - connectbase.world 로그인용 (당신, 개발자)              │
│     - SSO / 이메일 가입                                      │
│     - Public Key 발급, 결제, 앱 관리에 사용                      │
└─────────────────────────────────────────────────────────────┘
                            │
                            │ 발급
                            ▼
┌─────────────────────────────────────────────────────────────┐
│  ② Public Key (cb_pk_* / cb_sk_*)                              │
│     - 앱 단위로 발급 (개발자가 SDK·서버에 심음)              │
│     - 모든 SDK 호출의 기본 인증 수단                         │
│     - cb_pk_*: 클라이언트 노출 OK                            │
│     - cb_sk_*: 서버 전용 (절대 노출 금지)                    │
└─────────────────────────────────────────────────────────────┘
                            │
                            │ 앱 멤버 로그인 후
                            ▼
┌─────────────────────────────────────────────────────────────┐
│  ③ App Member JWT (access_token / refresh_token)            │
│     - 앱의 최종 사용자 (End User)                            │
│     - signUpMember/signInMember/oauth.signIn 으로 발급       │
│     - SDK가 자동으로 헤더에 첨부                             │
└─────────────────────────────────────────────────────────────┘

대부분의 경우:

클라이언트 SDK: ② cb_pk_ + ③ JWT (앱 사용자가 로그인하면 SDK가 알아서 처리)
서버 SDK: ② cb_sk_ 만 사용 (모든 권한)

② Public Key 종류

키 유형	접두사	사용 위치	권한
Public Key	`cb_pk_`	브라우저 / 모바일 앱 / 클라이언트	제한적 (앱 사용자 인증 + Public 엔드포인트)
Secret Key	`cb_sk_`	서버 (Node.js, Express, Cloud Function)	전체 권한

⚠️ 절대 cb_sk_* 키를 클라이언트 코드에 넣지 마세요. 빌드된 JS 번들에 포함되어 누구나 추출할 수 있습니다.

Public Key 발급 절차

https://connectbase.world 로그인
좌측 앱(Apps) → 사용할 앱 선택 (또는 새 앱 생성)
설정(Settings) → Public Keys 탭
새 Public Key 생성 클릭
키 이름 입력 → Public 또는 Secret 선택 → 생성
생성된 키를 즉시 복사 (한 번만 표시됩니다)

발급 직후 흐름

콘솔에서 키 생성
       │
       ▼
.env 에 저장 (VITE_CONNECT_BASE_PUBLIC_KEY=cb_pk_xxx)
       │
       ▼
SDK 초기화 (new ConnectBase({ publicKey: ... }))
       │
       ▼
첫 호출 (cb.database.getData(...))

SDK 초기화 (클라이언트 vs 서버)

클라이언트 (브라우저, React, Vue, RN)

typescript

import ConnectBase from 'connectbase-client'

// ✅ Public Key 사용
const cb = new ConnectBase({
  publicKey: import.meta.env.VITE_CONNECT_BASE_PUBLIC_KEY // cb_pk_...
})

서버 (Node.js, Express, Worker)

typescript

import 'dotenv/config'
import ConnectBase from 'connectbase-client'

// ✅ Secret Key 사용 (전체 권한)
const cbServer = new ConnectBase({
  secretKey: process.env.CONNECT_BASE_SECRET_KEY // cb_sk_...
})

같은 connectbase-client 패키지지만 키 종류만 다릅니다.

REST API 직접 호출

SDK 없이 fetch / curl 로 호출할 때:

bash

curl -X GET https://api.connectbase.world/v1/public/tables/tbl_xxx/data \
  -H "X-Public-Key: cb_pk_your_public_key"

헤더 이름은 X-Public-Key 입니다.

③ 앱 멤버(End User) 인증

앱의 최종 사용자(End User)가 회원가입/로그인하는 흐름입니다. SDK는 signUpMember / signInMember 호출 후 access_token을 자동으로 헤더에 첨부합니다.

회원가입 (login_id + password)

typescript

// cb.auth.signUpMember({ login_id, password, nickname })
const result = await cb.auth.signUpMember({
  login_id: 'myuser123',
  password: 'password123!',
  nickname: '홍길동'
})

console.log('member_id:', result.member_id)
console.log('access_token:', result.access_token) // SDK가 이미 자동 저장

내 정보 조회 / 로그아웃

typescript

const me = await cb.auth.getMe()
console.log(me.nickname, me.custom_data)

await cb.auth.signOut()

게스트 로그인 (실시간 채팅 등에 사용)

typescript

const guest = await cb.auth.signInAsGuestMember()
await cb.realtime.connect({ accessToken: guest.access_token })

토큰 생명주기 & 자동 갱신

signInMember()
   │
   ├─→ access_token  (수명 짧음, 모든 요청 헤더에 첨부)
   │
   └─→ refresh_token (수명 김, access_token 만료 시 재발급)

[access_token 만료]
   │
   ▼
SDK 자동: refresh_token 으로 /v1/auth/re-issue 호출
   │
   ├─→ 성공 → onTokenRefresh 콜백 호출 → 새 토큰으로 재시도
   │
   └─→ 실패 (refresh_token 도 만료) → onTokenExpired 콜백 호출

typescript

const cb = new ConnectBase({
  publicKey: 'cb_pk_...',

  // 토큰이 갱신될 때마다 호출 — localStorage 등에 저장하면 새로고침 후 복원 가능
  onTokenRefresh: ({ accessToken, refreshToken }) => {
    localStorage.setItem('cb_access_token', accessToken)
    localStorage.setItem('cb_refresh_token', refreshToken)
  },

  // refresh_token도 만료된 경우 (재로그인 필요)
  onTokenExpired: () => {
    localStorage.removeItem('cb_access_token')
    localStorage.removeItem('cb_refresh_token')
    window.location.href = '/login'
  }
})

// 페이지 로드 시 토큰 복원
const saved = localStorage.getItem('cb_access_token')
const refresh = localStorage.getItem('cb_refresh_token')
if (saved && refresh) {
  cb.setTokens(saved, refresh)
}

소셜 로그인 (OAuth)

지원 프로바이더: google, naver, github, discord

typescript

// 1. 로그인 버튼 클릭 시
await cb.oauth.signIn('google', 'https://myapp.com/oauth/callback')
// → Google 로그인 페이지로 리다이렉트
// → 완료 후 callbackUrl?access_token=...&refresh_token=... 로 돌아옴

typescript

// 2. 콜백 페이지에서
const result = cb.oauth.getCallbackResult()
if (result?.error) {
  console.error('로그인 실패:', result.error)
} else if (result) {
  console.log('로그인 성공:', result.member_id)
  cb.setTokens(result.access_token, result.refresh_token)
  window.location.href = '/'
}

OAuth 콜백 후에는 SDK가 access_token을 자동으로 발급하지 않습니다. 콜백 페이지에서 getCallbackResult() → setTokens() 패턴으로 직접 적용해야 합니다.

활성화된 프로바이더 목록 조회:

typescript

const { providers } = await cb.oauth.getEnabledProviders()
// [{ provider: 'google', client_id: '...' }, ...]

보안 권장사항

Secret Key는 절대 클라이언트에 노출하지 마세요 — .env, .env.local 파일은 .gitignore에 포함
환경 변수로 키를 관리하세요 — 코드에 하드코딩 금지
키를 주기적으로 순환하세요 — 콘솔에서 새 키 발급 → 적용 → 이전 키 폐기
최소 권한 원칙을 적용하세요 — 클라이언트는 cb_pk_* 만 사용

typescript

// ✅ 좋은 예
const cb = new ConnectBase({
  publicKey: import.meta.env.VITE_CONNECT_BASE_PUBLIC_KEY
})

// ❌ 나쁜 예 — 키가 코드에 하드코딩됨
const cb = new ConnectBase({
  secretKey: 'cb_sk_actual_secret_key_here'
})

다음 단계

SDK 설치

첫 번째 앱 만들기