API 키 관리

API 키는 Connect Base 리소스에 접근하기 위한 인증 수단입니다.

API 키 종류

키 종류	접두사	사용 위치	권한
Public Key	`cb_pk_`	브라우저 / 모바일 / 클라이언트	제한적 (앱 사용자 인증 + Public 엔드포인트)
Secret Key (유저 레벨)	`cb_sk_`	서버, MCP, 터널 CLI	전체 권한 (유저 소유 앱 관리)

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

API 키 발급

콘솔에서 발급 (권장)

https://connectbase.world 로그인
앱(Apps) → 사용할 앱 선택 Public Key (cb_pk_) — 앱별 키
콘솔 → 앱 선택 → 설정 → Public Keys 탭
새 Public Key 생성 클릭
키 이름 입력 → 생성
생성된 키를 즉시 복사 (한 번만 표시)

Secret Key (cb_sk_) — 유저 레벨 키 (앱과 무관)

콘솔 우상단 프로필 → 계정 설정 → Secret Keys
새 Secret Key 생성 클릭
키 이름 입력 → 생성
생성된 키를 즉시 복사 (한 번만 표시)

📌 두 키 종류는 별도 엔드포인트에서 관리됩니다. Public Key 는 앱별(/v1/apps/:appID/public-keys), Secret Key 는 유저별(/v1/user/secret-keys)이며 SDK 의 cb.publicKey 모듈은 Public Key 만 다룹니다. Secret Key 발급은 콘솔 UI 또는 REST 로만 가능합니다.

SDK로 발급 (콘솔 사용자 JWT 필요)

cb.publicKey 모듈은 콘솔 사용자 세션이 필요합니다 — 일반 SDK 호출에는 사용되지 않으며, 콘솔 자동화 / CI 파이프라인 같은 특수 케이스에서만 사용됩니다.

typescript

import ConnectBase from 'connectbase-client'

const cb = new ConnectBase({ /* 콘솔 사용자 세션 토큰 필요 */ })

// 키 생성
const created = await cb.publicKey.createPublicKey('app_xxx', {
    name: 'Production Public Key',
    expires_at: '2026-12-31T23:59:59Z'  // 선택, 미지정 시 무제한
})

console.log(created.key)         // 전체 키 — 생성 시 한 번만 반환
console.log(created.key_prefix)  // 표시용 앞 12자리
console.log(created.id)

CreatePublicKeyResponse 필드:

필드	타입	설명
`id`	string	키 ID
`name`	string	키 이름
`key`	string	전체 키 값 (생성 시에만 반환)
`key_prefix`	string	키 앞 12자리 (목록 표시용)
`is_active`	boolean	활성화 여부
`expires_at`	string \| undefined	만료일 (ISO 8601)
`created_at`	string	생성일

📌 SDK 의 Public Key 생성 요청은 {name, expires_at?} 두 필드만 지원합니다. permissions 필드는 존재하지 않으며, 권한은 cb_pk_ / cb_sk_ 접두사로 결정됩니다.

API 키 목록 조회 / 수정 / 삭제

typescript

// 목록
const list = await cb.publicKey.getPublicKeys('app_xxx')
list.public_keys.forEach((k) => {
    console.log(k.id, k.name, k.key_prefix, k.is_active)
})

// 비활성화 (또는 이름 변경)
await cb.publicKey.updatePublicKey('app_xxx', 'key_id', {
    is_active: false
})

// 삭제
await cb.publicKey.deletePublicKey('app_xxx', 'key_id')

키 사용 예시

클라이언트 (Public Key)

typescript

// .env
// VITE_CONNECT_BASE_PUBLIC_KEY=cb_pk_your_public_key

import ConnectBase from 'connectbase-client'

const cb = new ConnectBase({
    publicKey: import.meta.env.VITE_CONNECT_BASE_PUBLIC_KEY
})

서버 (Secret Key)

typescript

// .env
// CONNECT_BASE_SECRET_KEY=cb_sk_your_secret_key

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

const cbServer = new ConnectBase({
    secretKey: process.env.CONNECT_BASE_SECRET_KEY
})

REST API 직접 호출

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 입니다. Authorization: Bearer 가 아닙니다.

보안 모범 사례

1. 환경 변수 사용

bash

# .env (반드시 .gitignore 에 포함)
VITE_CONNECT_BASE_PUBLIC_KEY=cb_pk_xxx
CONNECT_BASE_SECRET_KEY=cb_sk_xxx

typescript

// 코드에서 직접 키를 하드코딩하지 마세요
const cb = new ConnectBase({
    secretKey: process.env.CONNECT_BASE_SECRET_KEY
})

2. 정기적인 키 로테이션

typescript

// 1) 새 키 생성
const newKey = await cb.publicKey.createPublicKey('app_xxx', { name: 'rotated-2026Q1' })

// 2) 새 키를 환경 변수로 배포 → 애플리케이션 재시작

// 3) 이전 키 비활성화
await cb.publicKey.updatePublicKey('app_xxx', 'old_key_id', { is_active: false })

// 4) 검증 후 삭제
await cb.publicKey.deletePublicKey('app_xxx', 'old_key_id')

3. 키 노출 시 대응

콘솔에서 즉시 해당 키 비활성화/삭제
새 키 생성 및 배포
콘솔 로그(Logs) 메뉴에서 무단 사용 흔적 점검

보안 개요

CORS 설정