Guide
Authentication
API 인증 및 키 관리
인증
01.software API는 두 가지 키를 사용하여 인증합니다.
API 키 종류
Client Key
용도: 브라우저/클라이언트에서 사용
- 공개해도 안전한 키
- 읽기 전용 작업에 사용
- 테넌트 식별에 사용
// 브라우저에서 사용
const client = createBrowserClient({
clientKey: process.env.NEXT_PUBLIC_SOFTWARE_CLIENT_KEY!
})Secret Key
용도: 서버에서만 사용
- 절대 클라이언트에 노출하면 안 됨
- 쓰기 작업 및 민감한 API에 사용
- JWT 토큰 생성에 사용
// 서버에서만 사용
const client = createServerClient({
clientKey: process.env.NEXT_PUBLIC_SOFTWARE_CLIENT_KEY!,
secretKey: process.env.SOFTWARE_SECRET_KEY!
})Secret Key를 클라이언트 코드에 포함하거나 NEXT_PUBLIC_ 접두사를 붙이지 마세요.
환경 변수 설정
.env.local
# 브라우저에서 접근 가능 (공개)
NEXT_PUBLIC_SOFTWARE_CLIENT_KEY=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
# 서버에서만 접근 가능 (비공개)
SOFTWARE_SECRET_KEY=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxVercel
- Vercel 대시보드 → Project Settings → Environment Variables
- 각 환경(Production, Preview, Development)에 키 추가
Docker
ENV NEXT_PUBLIC_SOFTWARE_CLIENT_KEY=your-client-key
ENV SOFTWARE_SECRET_KEY=your-secret-key클라이언트 사용
Browser Client
브라우저 환경에서 사용하는 클라이언트입니다.
import { createBrowserClient } from '@01.software/sdk'
const client = createBrowserClient({
clientKey: process.env.NEXT_PUBLIC_SOFTWARE_CLIENT_KEY!
})
// 사용 가능한 기능
client.from('products').find() // 조회
client.from('products').findById() // 단일 조회
client.query.useCollection() // React Query 훅특징:
- React Query 훅 제공 (
client.query) - 클라이언트 컴포넌트에서 사용
- 읽기 작업에 최적화
Server Client
서버 환경에서 사용하는 클라이언트입니다.
import { createServerClient } from '@01.software/sdk'
const client = createServerClient({
clientKey: process.env.NEXT_PUBLIC_SOFTWARE_CLIENT_KEY!,
secretKey: process.env.SOFTWARE_SECRET_KEY!
})
// 사용 가능한 기능
client.from('products').find() // 조회
client.from('products').create() // 생성
client.from('products').update() // 수정
client.from('products').remove() // 삭제
client.api.createOrder() // 주문 생성 API특징:
- Server Component, API Route에서 사용
- 모든 CRUD 작업 가능
- 주문/결제 관련 API 제공
인증 흐름
브라우저 요청
Browser → API Server
Client Key (Header: X-Client-Key)브라우저 클라이언트는 Client Key를 헤더에 포함하여 요청합니다.
서버 요청
Your Server → API Server
JWT Token (Header: Authorization: Bearer ...)서버 클라이언트는 Secret Key로 JWT 토큰을 생성하여 요청합니다.
권한
읽기 (Read)
- Browser Client: Client Key만으로 가능
- Server Client: Client Key + Secret Key 필요
쓰기 (Create/Update/Delete)
- Browser Client: 지원하지 않음
- Server Client: Client Key + Secret Key 필요
주문/결제 API
- Browser Client: 지원하지 않음
- Server Client: Client Key + Secret Key 필요
보안 모범 사례
Do's
- 환경 변수로 키 관리
- Secret Key는 서버에서만 사용
- 정기적으로 키 로테이션
Don'ts
- Secret Key를 코드에 하드코딩하지 않기
- Secret Key에
NEXT_PUBLIC_접두사 사용하지 않기 - Secret Key를 Git에 커밋하지 않기
API 키 발급
- 01.software Admin Panel에 로그인
- 테넌트 설정으로 이동
- API Keys 섹션에서 새 키 발급
Secret Key는 생성 시 한 번만 표시됩니다. 안전한 곳에 저장하세요.