레퍼런스개발자 레퍼런스
인증
슈츠 API를 안전하게 사용하기 위한 인증 방법을 알아봅니다.
API 키 개요
API 키란?
API 키는 외부 애플리케이션이 슈츠 워크스페이스에 접근할 수 있도록 허용하는 인증 수단입니다. 각 API 키는:
- 특정 워크스페이스에 연결됩니다
- 설정된 권한 범위 내에서만 동작합니다
- 생성 시 한 번만 표시되며, 이후에는 확인할 수 없습니다
키 형식
슈츠 API 키는 다음 형식을 따릅니다:
sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx (프로덕션)
sk_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx (테스트)API 키 생성
1단계: 개발자 설정 접근
- 워크스페이스 사이드바에서 설정 클릭
- 개발자 설정 탭 선택
- API 키 섹션으로 이동
2단계: 새 API 키 생성
+ 새 API 키 버튼을 클릭합니다.
3단계: 키 설정
| 설정 항목 | 설명 | 예시 |
|---|---|---|
| 이름 | 키를 식별하는 이름 | "프로덕션 서버", "Zapier 연동" |
| 권한 범위 | 허용할 작업 범위 | read, write, admin |
| 만료 기간 | 키의 유효 기간 (선택) | 30일, 90일, 무제한 |
4단계: 키 저장
생성된 키는 한 번만 표시됩니다. 페이지를 벗어나면 다시 확인할 수 없으니 안전한 곳에 저장하세요.
sk_live_abc123def456ghi789jkl012mno345pqr678API 키 사용
모든 API 요청의 Authorization 헤더에 키를 포함합니다.
기본 사용법
curl -X GET "https://suits.work/api/v1/datamodels" \
-H "Authorization: Bearer sk_live_xxxxxxxxxxxx" \
-H "Content-Type: application/json"언어별 예시
JavaScript (fetch)
const response = await fetch('https://suits.work/api/v1/datamodels', {
method: 'GET',
headers: {
'Authorization': `Bearer ${process.env.SUITS_API_KEY}`,
'Content-Type': 'application/json',
},
});
const data = await response.json();Python (requests)
import os
import requests
response = requests.get(
'https://suits.work/api/v1/datamodels',
headers={
'Authorization': f'Bearer {os.environ["SUITS_API_KEY"]}',
'Content-Type': 'application/json',
}
)
data = response.json()권한 범위
API 키는 필요한 권한만 선택적으로 부여할 수 있습니다.
read (읽기)
데이터 조회 권한
- 데이터모델 목록 및 구조 조회
- 행(Row) 데이터 조회
- 페이지 내용 조회
- 파일 다운로드
GET /v1/datamodels
GET /v1/datamodels/:id/rows
GET /v1/pages/:idwrite (쓰기)
데이터 변경 권한 (read 포함)
- 행 생성, 수정, 삭제
- 페이지 생성, 수정, 삭제
- 파일 업로드
POST /v1/datamodels/:id/rows
PATCH /v1/datamodels/:id/rows/:rowId
DELETE /v1/datamodels/:id/rows/:rowIdadmin (관리)
시스템 관리 권한 (read, write 포함)
- 데이터모델 구조 변경 (속성 추가/삭제)
- 워크스페이스 설정 변경
- 멤버 관리
- API 키 관리
POST /v1/datamodels
PATCH /v1/datamodels/:id/properties
DELETE /v1/datamodels/:id보안 권장사항
API 키 보호
API 키를 코드에 직접 포함하지 마세요. 노출된 키는 즉시 폐기해야 합니다.
✅ 환경 변수 사용
# .env
SUITS_API_KEY=sk_live_xxxxxxxxxxxxconst apiKey = process.env.SUITS_API_KEY;✅ 시크릿 관리 서비스
- AWS Secrets Manager
- Google Cloud Secret Manager
- HashiCorp Vault
❌ 피해야 할 것
// ❌ 코드에 직접 포함
const apiKey = 'sk_live_xxxxxxxxxxxx';
// ❌ 클라이언트 사이드 노출
<script>const key = 'sk_live_xxx'</script>최소 권한 원칙
필요한 권한만 부여하세요:
| 용도 | 권장 권한 |
|---|---|
| 대시보드 표시용 | read |
| 폼 데이터 저장 | write |
| 자동화 통합 | write |
| 백오피스 관리 | admin |
주기적 갱신
보안 강화를 위해 API 키를 정기적으로 갱신하세요:
- 새 키를 먼저 생성
- 애플리케이션에 새 키 배포
- 기존 키 비활성화/삭제
에러 처리
401 Unauthorized
잘못된 API 키
{
"error": {
"code": "unauthorized",
"message": "Invalid or missing API key"
}
}확인사항:
- API 키가 올바른지 확인
Authorization: Bearer형식 확인 (Bearer 뒤 공백 필수)- 키가 비활성화되지 않았는지 확인
403 Forbidden
권한 부족
{
"error": {
"code": "forbidden",
"message": "Insufficient permissions for this operation"
}
}확인사항:
- API 키의 권한 범위 확인
- 요청하는 작업에 필요한 권한 확인
- write 작업에 read 권한만 있는지 확인
429 Too Many Requests
속도 제한 초과
{
"error": {
"code": "rate_limited",
"message": "Too many requests",
"retryAfter": 60
}
}확인사항:
- 요청 빈도 줄이기
- 지수 백오프(exponential backoff) 적용
- 대량 작업은 배치 API 사용
속도 제한 (Rate Limiting)
API 안정성을 위해 요청 속도를 제한합니다.
| 플랜 | 제한 |
|---|---|
| Free | 100 요청/분 |
| Pro | 1,000 요청/분 |
| Enterprise | 10,000 요청/분 |
응답 헤더
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1609459200