Caret API는 API 키 기반 인증을 사용합니다. 모든 API 요청에는 유효한 API 키가 필요합니다.
API 키 생성
- Caret 애플리케이션에서 워크스페이스 설정으로 이동
- API 키 섹션을 찾습니다
- “새 API 키 생성” 버튼을 클릭
- 키에 설명적인 이름을 지정 (예: “Production API”, “Testing”)
- 적절한 권한 선택
- “생성” 클릭
API 키는 생성 시점에 한 번만 표시됩니다. 안전한 곳에 저장하세요. 키를 분실한
경우 새로운 키를 생성해야 합니다.
인증 헤더
모든 API 요청에는 Authorization 헤더에 Bearer 토큰으로 API 키를 포함해야 합니다:
Authorization: Bearer sk-caret-api-xxxxxxxxxxxxxxxxxxxx
cURL
curl -X GET \
https://api.caret.so/v1/notes \
-H 'Authorization: Bearer sk-caret-api-xxxxxxxxxxxxxxxxxxxx' \
-H 'Content-Type: application/json'
JavaScript (fetch)
const response = await fetch('https://api.caret.so/v1/notes', {
headers: {
Authorization: 'Bearer sk-caret-api-xxxxxxxxxxxxxxxxxxxx',
'Content-Type': 'application/json',
},
});
Python (requests)
import requests
headers = {
'Authorization': 'Bearer sk-caret-api-xxxxxxxxxxxxxxxxxxxx',
'Content-Type': 'application/json'
}
response = requests.get('https://api.caret.so/v1/notes', headers=headers)
API 키 권한
API 키 생성 시 다음 권한을 선택할 수 있습니다:
읽기 권한
- 메모 조회
- 워크스페이스 정보 조회
- 멤버 정보 조회
쓰기 권한
- 메모 생성 및 업데이트
- 멤버 관리
- 워크스페이스 설정 변경
관리 권한
- API 키 관리
- 청구 정보 액세스
- 워크스페이스 삭제
보안을 위해 필요한 최소한의 권한만 부여하는 것을 권장합니다. 예를 들어, 메모를
읽기만 하는 통합의 경우 읽기 권한만 부여하세요.
API 키 관리
키 회전
정기적으로 API 키를 회전하는 것이 보안상 좋습니다:
- 새 API 키 생성
- 애플리케이션에서 새 키로 업데이트
- 이전 키 비활성화
키 비활성화
의심스러운 활동이 발견되거나 키가 손상된 경우:
- 워크스페이스 설정의 API 키 섹션으로 이동
- 해당 키 옆의 “비활성화” 버튼 클릭
- 필요한 경우 새 키 생성
인증 오류
잘못된 또는 누락된 인증 정보로 요청할 경우 다음 오류를 받게 됩니다:
{
"error": {
"code": "unauthorized",
"message": "Invalid API key",
"details": "The provided API key is invalid or has been revoked"
}
}
- API 키 누락 또는 잘못된 형식
- 비활성화되거나 삭제된 API 키
- 권한 부족
- 만료된 API 키
모범 사례
- API 키를 소스 코드에 직접 포함하지 마세요
- 환경 변수나 보안 설정 관리 도구 사용
- HTTPS를 통해서만 API 키 전송
- 정기적인 키 회전
개발 환경
# .env 파일
CARET_API_KEY=sk-caret-api-xxxxxxxxxxxxxxxxxxxx
# 애플리케이션에서 사용
const apiKey = process.env.CARET_API_KEY;
프로덕션 환경
- 안전한 키 관리 서비스 사용 (예: AWS Secrets Manager, Azure Key Vault)
- 키에 대한 접근 로그 모니터링
- 불필요한 권한 제거
