Caret API는 API 키 기반 인증을 사용합니다. 모든 API 요청에는 유효한 API 키가 필요합니다.

​
API 키 생성

  1. Caret 애플리케이션에서 워크스페이스 설정으로 이동
  2. API 키 섹션을 찾습니다
  3. “새 API 키 생성” 버튼을 클릭
  4. 키에 설명적인 이름을 지정 (예: “Production API”, “Testing”)
  5. 적절한 권한 선택
  6. “생성” 클릭
API 키 생성
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 키를 회전하는 것이 보안상 좋습니다:
  1. 새 API 키 생성
  2. 애플리케이션에서 새 키로 업데이트
  3. 이전 키 비활성화

​
키 비활성화

의심스러운 활동이 발견되거나 키가 손상된 경우:
  1. 워크스페이스 설정의 API 키 섹션으로 이동
  2. 해당 키 옆의 “비활성화” 버튼 클릭
  3. 필요한 경우 새 키 생성

​
인증 오류

잘못된 또는 누락된 인증 정보로 요청할 경우 다음 오류를 받게 됩니다: 
{
  "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)
  • 키에 대한 접근 로그 모니터링
  • 불필요한 권한 제거